Get Electricity Consumption
Description
Returns the electricity consumption on a specific service location during a specified range of time. The call support different aggregation levels to obtain different levels of details.
A range of time is always interpreted as a closed-open interval, meaning that the start is inclusive, the end is exclusive. So requesting all 5min intervals for e.g. Oct 10 2020 (timezone Europe/Brussels) is done with the following range: [1602280800000, 1602367200000) where 1602280800000 is the UTC timestamp for Oct 10th 2020 and 1602367200000 is the UTC timestamp for Oct 11th 2020 (both timezone Europe/Brussels). The interval with timestamp 1602280800000 is already part of the next day so you do not want that. Using an open interval avoid that you always have to take one step back and subtract 5mins from 1602280800000. You can simply decide on the start of your interval and add the duration you are interested in and we will do the rest.
TIP: To convert the 5 minute interval from Energy [Wh] to Power [W], like the Smappee Dashboard reports these, you have to do these values times 12 as there are 12 x 5 minute intervals in an hour.
Resource URL
https://app1pub.smappee.net/dev/v3/servicelocation/[SERVICELOCATIONID]/consumption
HTTP method
GET
HTTP header
Authorization: Bearer [ACCESS_TOKEN]
[ACCESS_TOKEN] being the access token received from the Get token or Refresh token authentication calls.
Parameters
Parameter | Type | Description |
|---|---|---|
SERVICELOCATIONID | Path Parameter | The actual id of an accessible service location (see Get Servicelocations) |
aggregation | Query Parameter | The level of detail and should be one of:
Additional aggregations have been added based on the collected 5 minute data to report in the interval of your market:
|
from | Query Parameter | The UTC timestamp in milliseconds indicating the beginning of the requested period |
to | Query Parameter | The UTC timestamp in milliseconds indicating the end of the requested period |
Example
https://app1pub.smappee.net/dev/v3/servicelocation/10236/consumption?aggregation=1&from=1585294200000&to=1585294800000
Result
Numbers are fictional and applied on a Smappee Genius series device
{
"serviceLocationId": 10236,
"consumptions": [
{
"timestamp": 1585294200000,
"consumption": 43.599,
"solar": 42.159,
"alwaysOn": 27.744,
"gridImport": 9.684,
"gridExport": 8.244,
"selfConsumption": 80.45,
"selfSufficiency": 77.79,
"active": [
null, null, null, 0.1, null, null, 0.0, 3.0, null, null, 0.2, 3.4, -1.9, 42.2, 5.7, 4.2, null, null, null, null, null, null, null, null, null, null, null, null
],
"reactive": [
null, null, null, 0.7, null, null, 0.4, 2.9, null, null, 1.0, 23.6, 36.9, 4.3, 2.8, 1.7, null, null, null, null, null, null, null, null, null, null, null, null
],
"voltages": [235.5, 236.6, 0.0],
"lineVoltages": [null, null, null],
"lineVoltagesMin": [null, null, null],
"lineVoltagesMax": [null, null, null],
"phaseVoltages": [235.5, 236.6, 0.0],
"phaseVoltagesMin": [234.6, 235.5, 0.0],
"phaseVoltagesMax": [236.4, 237.9, 0.0],
"current": [
null, null, null, 0.0, null, null, 0.0, 0.2, null, null, 0.1, 2.8, 3.0, 2.2, 0.3, 0.2, null, null, null, null, null, null, null, null, null, null, null, null
],
"currentMin": [
null, null, null, 0.0, null, null, 0.0, 0.0, null, null, 0.1, 1.4, 1.9, 1.3, 0.3, 0.2, null, null, null, null, null, null, null, null, null, null, null, null
],
"currentMax": [
null, null, null, 0.0, null, null, 0.0, 0.5, null, null, 0.1, 5.4, 4.9, 2.3, 0.3, 0.2, null, null, null, null, null, null, null, null, null, null, null, null
],
},
{
...
}
...
]
}The result depends on the type of energy monitor you're requesting data from. Table below gives an overview of the expected fields in the consumptions array.
Energy | Solar | Plus | Pro | Genius | Connect-series | |
|---|---|---|---|---|---|---|
timestamp (UTC, ms epoch) | ||||||
consumption (Wh) | ||||||
alwaysOn (Wh) | ||||||
solar (Wh) | (in case of solar) | (in case of solar) | (in case of solar) | (in case of solar) | ||
gridImport (Wh) | (in case of solar) | (in case of solar) | (in case of solar) | (in case of solar) | ||
gridExport (Wh) | (in case of solar) | (in case of solar) | (in case of solar) | (in case of solar) | ||
selfSufficiency (%) | (in case of solar) | (in case of solar) | (in case of solar) | (in case of solar) | ||
selfConsumption (%) | (in case of solar) | (in case of solar) | (in case of solar) | (in case of solar) | ||
active (Wh) (1) | ||||||
reactive (Wh) (1) | ||||||
voltages (V) (2) | ||||||
lineVoltages (V) (2) | ||||||
lineVoltagesMin (V) (2) | ||||||
lineVoltagesMax (V) (2) | ||||||
phaseVoltages (V) (2) | ||||||
phaseVoltagesMin (V) (2) | ||||||
phaseVoltagesMax (V) (2) | ||||||
current (A) (1) | ||||||
currentMin (A) (1) | ||||||
currentMax (A) (1) | ||||||
currentHarmonics | ||||||
voltageHarmonics |
(1) The values in the active, reactive and current, currentMin and currentMax lists can be matched to the correct measurement or channel as follows:
Smappee Pro/Plus: by using the "channelsConfiguration > inputChannels > ctInput" details returned with the Get Servicelocation info call.
Smappee Genius/Wi-Fi Connect: by using the "measurements > channels > consumptionIndex" returned with the Get metering configuration call.
(2) The voltage lists (i.e. voltages, lineVoltages, lineVoltagesMin and lineVoltagesMax, phaseVoltages, phaseVoltagesMin, phaseVoltagesMax) have a fixed length of 3 values. The order in which the values are being returned equal "L1, L2, L3".
The fields "phaseVoltagesMin", "phaseVoltagesMax", "lineVoltagesMin", "lineVoltagesMax", "currentMin" and "currentMax" are only available in case of Smappee Genius and if the Smappee license allows the collection of these values.
The fields "currentHarmonics" and "voltageHarmonics" hold a 2-dimensional array of harmonic values. The first index is the channel index (similar to “current” or “voltages”). The second index is the harmonic index.
Example: assuming the grid phase A load is at index 0, the 5th current harmonic for that load would be available at currentHarmonics(0, 5). The total harmonic distortion is at index 0 so available at currentHarmonics(0, 0). If the configuration is not requesting a harmonic index then that slot will simply be empty (null).
Versioning
Version 1 (v1)
This version of the API always returns "alwaysOn" values as W.
Version 2 (v2)
This version of the API returns "alwaysOn" values as Wh as soon as aggregation type is 2, 3, 4 or 5, i.e. when level of detail exceeds the lowest level of reporting of your market and we effectively need to aggregate data. When requesting 5 minute (based) data, the unit for alwaysOn is W.
Additional aggregation levels based on "aggregation" query parameter, possible values: 6, 7, 8 and 9. See above.
Version 3 (v3)
Up until this version of the API the consumption values were returned simply one after the other, returning up to 9 values for a PRO device. However, for Genius devices that have a lot more measurement slots and are highly configurable, some slots could end up not being used. In previous versions of the API, these unused slots were simply ignored making it very difficult to find the consumption values for the load that client code is interested in. As an example, the Genius device could be configured to measure phase A of the grid load at index 5 but due to unused slots, it would be possible for that to be returned at index 0. This version of the API will respect that index and return null, null, null, null, null, <value>,... instead. To match the measurements to their correct indices, one needs to use "consumptionIndex" returned with the Get metering configuration call.