Skip to content
Docs

EcoPhi API: Accessing data

All about which values you can retrieve and how to do it.

List all devices

GET /devices

Headers:

Authorization: Bearer $TOKEN

Example response:

Content type: application/json

{
  "device_ids": [
    "m156495",
    "m157254"
  ]
}
  • device_ids: all available device ids

List all resources of a device

GET /$DEVICE-ID/resources
  • $DEVICE-ID: one of the device ids returned by the previous method

Example request: GET https://api.ecophi.de/m156495/resources

Headers:

Authorization: Bearer $TOKEN

Example response:

Content type: application/json

{
  "device_id": "m156495",
  "resource_ids": [
    "all_data"
  ]
}
  • device_id: the requested device id
  • resource_ids: all available resource ids of that device (for most users, only the resource all_data is available)

List all values of a resource

GET /$DEVICE-ID/$RESOURCE-ID/values
  • $DEVICE-ID: one of the available device ids
  • $RESOURCE-ID: one of the resources returned by the previous method

Example request: GET https://api.ecophi.de/m156495/all_data/values

Headers:

Authorization: Bearer $TOKEN

Example response:

Content type: application/json

{
  "device_id": "m156495",
  "resource_id": "all_data",
  "values": [
    "e_00_00_00_000_total_solar_energy",
    "e_00_00_00_000_total_other_energy",
    "e_00_00_00_000_total_load_energy"
  ]
}
  • device_id: the requested device id
  • resource_id: the requested resource id
  • values: all available value ids of that resource

Available values

Which values are available largely depends on what is monitored with your EcoPhi system: for example which sensors are connected (temperature, humidity, irradiation, etc.) or what the make of your inverter is. The possible values are just as versatile as the EcoPhi monitoring.

However, there are values that are present for each device:

Meta

  • values_id: Most often the Modbus ID; identifier for a specific readout on device level (can be used to filter for the values of one specific readout, values of other readouts will be NULL in that row)
  • protocol_id: The id of the selected readout protocol

Alerts

  • alarm_index: Unique - on device level - ID of a triggered alert
  • alarm_name: Name of the triggered alert

Energy

  • e_03_07_04_000_total_solar_energy: All energy from solar inverters combined (in kWh)

  • e_03_07_04_000_total_load_energy: All energy which goes to the load combined (in kWh)

  • e_03_07_04_000_total_battery_energy: All energy from battery inverters combined (in kWh)

  • e_03_07_04_000_genset_energy: All energy from gensets combined (in kWh)

  • e_03_07_04_000_total_export_energy: All energy which has been exported (in kWh)

  • e_03_07_04_000_total_other_energy: All energy from other sources - which will mainly be the grid - combined (in kWh)

Power

  • e_03_01_00_000_total_solar_power: All power from solar inverters combined (in kW)

  • e_03_01_00_000_total_load_power: All power which goes to the load combined (in kW)

  • e_03_01_00_000_total_battery_power: All power from battery inverters combined (in kW)

  • e_03_01_00_000_genset_power: All power from gensets combined (in kW)

  • e_03_01_00_000_total_other_power: All power from other sources - which will mainly be the grid - combined (in kW)

Calculated savings

  • e_00_00_04_000_money_saved: Money saved according to total solar energy and the set multiplier (changing the multiplier will only affect future values)

  • e_00_00_04_000_revenue_created: Revenue created according to total solar energy and the selected multiplier (changing the multiplier will only affect future values)

  • e_03_23_04_000_CO2_saved: CO2 saved according to total solar energy and the selected multiplier (changing the multiplier will only affect future values)

  • e_00_00_04_000_trees_saved: Trees saved according to total solar energy and the selected multiplier (changing the multiplier will only affect future values)

Calculation parameters

  • e_00_00_00_000_money_per_kWh: the set multiplier for money saved at that time

  • e_00_00_00_000_revenue_per_kWh: the set multiplier for revenue created at that time

  • e_00_00_00_000_CO2_saved_per_kWh: the set multiplier for CO2 saved at that time

  • e_00_00_00_000_trees_saved_per_kWh: the set multiplier for trees saved at that time

Audit Box only

  • e_00_00_00_000_days_remaining: Remaining credit of days for monitoring

Value name explanation

The value names contain codes that describe the value behind it.

Example: e_03_02_00_001_AC_activepower_L1

Unit PrefixUnitValue TypeValues IDName
e030200001AC_activepower_L1

Unit prefix

CodeMeaning
00none
01m
02M
03k

Unit

CodeMeaning
00none
01W
02V
03A
04°C
05%
06Hz
07Wh
08Varh
09VA
10pH
11bar
12W/m²
13RPM
14m³/h
15var
16h
17Degree
18m/Min
19liter
20m
21Ohm
22Pa
23g
24min
25day
26month
27Ah
28byte
29m/s
30Vah

Value Type

CodeMeaning
00continous
01pulse
02digital
03text
04cumulative
05cumulative with reset every day
06status

Values ID

This is most often the Modbus ID. It can also be present as a value itself (values_id; see above under Available values).

Get data

GET /data/$DEVICE-ID/$RESOURCE-ID?values=$VALUE-LIST&from=$FROM&to=$TO
  • $DEVICE-ID: one of the available device ids
  • $RESOURCE-ID: one of the available resource ids

Query parameters:

  • $VALUE-LIST: one value or several values separated by commas (important: no spaces)
  • $FROM: start of the time interval from which the data should be retrieved in the format YYYYMMDDTHHMMSS in UTC
  • $to: end of the time interval from which the data should be retrieved in the format YYYYMMDDTHHMMSS in UTC

Example request:

GET https://api.ecophi.de/data/m156495/sensors?values=e_03_07_04_000_total_solar_energy,e_03_07_04_000_total_other_energy&from=20210801T123000&to=20210801T180000

Limits per request:

  • maximum number of values: 20
  • maximum time interval: 7 days

Headers:

Authorization: Bearer $TOKEN

Example response:

Content type: application/json

[
  {
    "timestamp": "2021-08-01T12:30:07",
    "e_03_07_04_000_total_solar_energy": 543,
    "e_03_07_04_000_total_other_energy": 0
  },
  {
    "timestamp": "2021-08-01T12:30:38",
    "e_03_07_04_000_total_solar_energy": 544,
    "e_03_07_04_000_total_other_energy": 0
  },


  ...
]
  • timestamp: UTC timestamp
  • values_id: always provided in response, DO NOT request it in the $VALUE-LIST