SmartMeter
HTTP API for Smart Meter Integration
This API allows you to manage your Voltaware sensors or smart meters and carry out a variety of operations.
The main operations that can be performed are to retrieve disaggregation results and set up metadata needed for our disaggregation algorithms for each device.
This API is organised around JSON and REST.
Base API URL
https://smart-meter-reseller-api.voltaware.com
Versioning
Rolling releases with no breaking changes.
Debugging/Status code
| Status Code | Description |
|---|---|
200 |
Okay: Standard response for successful HTTP requests |
204 |
Success: The server successfully processed the request and there is nothing to return |
401 |
Unauthorized: You need to generate the access token (see below) |
403 |
Unauthenticated: Please ensure that you are sending the event data (even a single data point is sufficient) prior to any metadata to ensure that the corresponding device is correctly registered on the system. Note that, for a new device, after sending an event through the MQTT message, you would need to reconnect to the API in order to update the cache with the new device before sending any metadata. Otherwise, it would still results in the 403 response. |
404 |
Not Found: This is not exactly an error. It just means that the resource that you are looking for was not found |
If you encounter any other status response codes, then please get in touch with Voltaware.
Authentication
You must use the credentials issued by Voltaware with the endpoint /auth/token to generate an access token.
Authentication to the API is performed by submitting the access token in the request header Authorization: Bearer access_token.
The access token will expire after 12 hours they are issued, after this period you will need to refresh it.
To refresh the access token use the endpoint /auth/token/refresh.
Access Token
HTTP request
POST /auth/token
Request header
Content-Type: application/json
Request body
{
"grant_type": "client_credentials",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}
Response body
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in_secs": 43200,
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}
Issues a new access token. This endpoint must be called before any other call to other endpoints are performed. You must reuse the token until it expires instead of creating a new one for each request.
Refresh Token
HTTP request
POST /auth/token/refresh
Request headers
Content-Type: application/json
Request body
{
"grant_type": "refresh_token",
"client_id": "YOUR_CLIENT_ID",
"refresh_token": "YOUR_REFRESH_TOKEN"
}
As the access token is valid for 12 hours, when the access token expires all requests with the expired acess token will receive an HTTP error code 401. You will need to refresh your token using this endpoint.
Response body
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in_secs": 43200
}
Devices
Provides detailed information about devices.
List all devices
HTTP request
GET /sensors
Request headers
Authorization: Bearer access_token
Response body
[
0001,
0002,
0003
]
Retrieves a list of IDs for all your available devices. The response includes all Smart Meters that have sent at least one data point to our backend, as well as any Voltaware sensors that belong to your account.
View single sensor
HTTP request
GET /sensors/{device_id}
Request headers
Authorization: Bearer access_token
Response body
{
"connection_state": "connected",
"firmware": "112356",
"last_event": "2020-12-08T15:23:05Z",
"first_event": "2018-06-08T10:20:51.287Z",
"locale": {
"isoCountryCode": "DE",
"isoLocaleCode": "de-DE",
"timeZoneId": "Europe/Berlin",
"userDefinedLanguage": "pt-BR"
}
}
| Field name | Description |
|---|---|
connection_state enum, nullable |
Available for Voltaware sensors. Possible values are connected, disconnected, and never_connected |
firmware string, nullable |
Available for Voltaware sensors |
first_event ISO timestamp UTC |
Timestamp of the first data point received on our backend |
last_event ISO timestamp UTC |
Timestamp of the last data point received on our backend |
locale.isoCountryCode string |
Country code of the device |
locale.isoLocaleCode string |
Locale code of the device |
locale.timeZoneId string |
Time zone of the device |
locale.userDefinedLanguage string |
Deprecated field |
Metadata
It is only possible to provide metadata for a smart meter after we receive at least one data point for consumption in our broker. Otherwise, the smart meter will not exist on our platform, and you will receive a 'Forbidden' response status.
Property
In order to provide you with more accurate Disaggregation results we need to get some information regarding the property where the sensor is installed and some information about the appliances owned by the end user.
We remind you that the Voltaware algorithm is designed to work in households and that we currently do not support users that produce energy (solar pannels, batteries...)
View property details
GET /sensors/{device_id}/metadata/property
Response body
{
"property_type": "HOME",
"home_type": "FLAT",
"home_size": 49.8,
"bedroom_amount": 2,
"power_generator_source": "SOLAR",
"people_amount": 2,
"people_amount_in_day_time": 0,
"people": [
{
"age_range": "ADULT",
"amount": 2
}
],
"version": "1.0"
}
View property details.
Set up property details
PUT /sensors/{device_id}/metadata/property
Request body for
home_typehouse
{
"property_type": "HOME",
"home_type": "HOUSE",
"home_usage_type": "PRIMARY",
"home_size": 80,
"bedroom_amount": 2,
"power_generator_source": "NONE",
"people_amount": 3,
"people_amount_in_day_time": 2,
"people": [
{
"age_range": "ADULT",
"amount": 2
},
{
"age_range": "ZERO_TO_FIVE",
"amount": 1
}
],
"version": "1.0"
}
Request body for
home_typeoffice, commercial or industry
{
"property_type": "INDUSTRY",
"power_generator_source": "SOLAR",
"version": "1.0"
}
Setup the property details associated to a sensor by providing the following information:
In case the property_type is OFFICE, COMMERCIAL, INDUSTRIAL, the following are the fields needed in the request body.
| Field name | Description |
|---|---|
property_type string (enum), required |
OFFICE, COMMERCIAL, INDUSTRIAL |
power_generator_source string (enum), required |
SOLAR, HYDROELECTRICITY, WIND, BATTERY, OTHER, NONE |
version string, required |
The current version of the property information is 1.0 |
In case the property_type is HOME, we will require a number of information in order to be able to classify people’s homes and create clusters to compare them to similar users.
| Field name | Description |
|---|---|
property_type string (enum), required |
HOME |
home_type string (enum), required |
FLAT, HOUSE |
home_usage_type string (enum), required |
PRIMARY, SECONDARY |
home_size float, required |
Size of the house in square meters |
bedroom_amount int, required |
Minimum value is 1 |
power_generator_source string (enum), required |
SOLAR, HYDROELECTRICITY, WIND, BATTERY, OTHER, NONE |
people_amount int, required |
Minimum value is 1 |
people_amount_in_day_time int, required |
Minimum value is 0 |
people array, required |
The field must be present in the JSON but it can receive an empty array. |
people[].age_range string (enum), required |
ZERO_TO_FIVE, SIX_TO_EIGHTEEN, ADULT, PENSIONER |
people[].amount int, required |
|
version string, required |
The current version of the property information is 1.0 |
Appliances
View property appliances
GET /sensors/{device_id}/metadata/appliances
Response body
{
"appliances": [
{
"key": "AC",
"amount": 1,
"type": "CENTRALISED",
"usage_type": "SUMMER"
},
{
"key": "AC",
"amount": 1,
"type": "WINDOW",
"usage_type": "BOTH"
},
{
"key": "ELECTRIC_BOILER",
"amount": 1,
"usage_type": "SPACE_HEATING",
"coupled_with_solar_thermal_system": "NO",
"water_tank": false
},
{
"key": "ELECTRIC_BOILER",
"amount": 1,
"usage_type": "WATER_HEATING",
"coupled_with_solar_thermal_system": "YES",
"water_tank": true
},
{
"key": "FRIDGE",
"amount": 1,
"type": "FRIDGE"
},
{
"key": "GAS_HEATING",
"amount": 1,
"any_electric_heater": false
},
{
"key": "ELECTRIC_OVEN",
"amount": 1,
"type": "REGULAR"
},
{
"key": "OTHER",
"amount": 1,
"name": "A Electronic Device"
},
{
"key": "OTHER",
"amount": 1,
"name": "A Different Electronic Device"
}
],
"version": "1.0"
}
View property appliances.
Set up property appliances
PUT /sensors/{device_id}/metadata/appliances
Request body
{
"appliances": [
{
"key": "AC",
"amount": 1,
"type": "MINI_SPLIT",
"usage_type": "BOTH"
},
{
"key": "DEHUMIDIFIER",
"amount": 1
},
{
"key": "DISHWASHER",
"amount": 1
},
{
"key": "ELECTRIC_BOILER",
"amount": 1,
"usage_type": "WATER_HEATING",
"coupled_with_solar_thermal_system": "NO",
"water_tank": true
},
{
"key": "ELECTRIC_HEATING",
"amount": 1,
"type": "UNDERFLOOR"
},
{
"key": "ELECTRIC_LAWN_MOWER",
"amount": 1
},
{
"key": "ELECTRIC_OVEN",
"amount": 1,
"type": "MICROWAVE" | "MINI" | "REGULAR"
},
{
"key": "ELECTRIC_SHOWER",
"amount": 2
},
{
"key": "ELECTRIC_STOVE",
"amount": 1,
"type": "ELECTRIC" | "INDUCTION"
},
{
"key": "ELECTRIC_VEHICLE",
"amount": 1,
"type": "CAR",
"wattages": [7200]
},
{
"key": "ELECTRIC_VEHICLE",
"amount": 2,
"type": "BIKE",
"wattages": [750, 750]
},
{
"key": "FRIDGE",
"amount": 1,
"type": "FRIDGE_AND_FREEZER"
},
{
"key": "FRIDGE",
"amount": 1,
"type": "FREEZER"
},
{
"key": "GAS_HEATING",
"amount": 1,
"any_electric_heater": true
},
{
"key": "HUMIDIFIER",
"amount": 1
},
{
"key": "JACUZZI",
"amount": 1
},
{
"key": "KETTLE",
"amount": 1
},
{
"key": "POOL_PUMP",
"amount": 1
},
{
"key": "TUMBLE_DRYER",
"amount": 1,
"type": "I_DONT_KNOW",
"usage_types": ["AUTUMN", "SPRING", "WINTER"]
},
{
"key": "WASHING_MACHINE",
"amount": 1
},
{
"key": "OTHER",
"amount": 3,
"name": "Sprinklers"
}
],
"version": "1.0"
}
For each appliance object sent, all fields are required.
In case a user doesn’t know an answer or if a question is too technical for them, they will always be able to select the option “I don’t know”. These information allow us to improve the accuracy of our algorithm and help us prioritize our future work.
AC
For the AC, we want to know what type of AC the user has as well as the season when the user uses it. In case the user uses an AC during cold months, this appliance will be displayed on the disaggregation results as Heating.
• For the type, the accepted values are: CENTRALISED, MINI_SPLIT, WINDOW, OTHER or I_DONT_KNOW.
• For the usage_type, the accepted values are: SUMMER, WINTER or BOTH.
ELECTRIC BOILER (ELECTRIC WATER HEATER)
For this appliance, we want to know how many units the user have, if the Boiler is used for heating up space or water (or both), if it is coupled with a solar thermal system and if it has a water tank or not.
• For the usage_type, the accepted values are: SPACE_HEATING, WATER_HEATING or BOTH.
• For the coupled_with_solar_thermal_system, the accepted values are: YES, NO or NOT_SURE.
• For the water_tank, the accepted values must be of the type BOOLEAN.
ELECTRIC HEATING (SPACE HEATING)
With the Electric Heating questions we want to know if the user has an electric or gas main heating source, depending on this first answer, we will ask different questions to the user. In case they have an electric main heating source we will ask the type of Heater they have, in case they say it’s gas we will ask whether they have additional electric heating units.
In case they say Electrical:
• For the type, the accepted values are: HEAT_PUMP, HEAT_STORAGE, RADIATOR, UNDERFLOOR or OTHER.
In case they say Gas:
• For the any_electric_heater, the accepted values must be of the type BOOLEAN.
ELECTRIC OVEN
Regarding the electric oven question, we want to know what type of oven the user has and how many of each.
• For the type, the accepted values are: MICROWAVE, MINI or REGULAR. Followed by each type’s quantity.
ELECTRIC OR INDUCTION STOVE
For the stove, we want to know what type of stove the user has.
• For the type, the accepted values are: ELECTRIC or INDUCTION.
ELECTRIC VEHICLE
In case of the electric vehicles, we want to know the type of vehicle the user has, how many and if they know the wattage of their chargers.
• For the type, the accepted values are: BIKE, CAR, MOTORBIKE, SCOOTER.
• For the wattages, the accepted values are a list of integers of size equal to the amount of the corresponding vehicle.
FRIDGE/FREEZER
In case of the fridge (or cooling devices), we want to know the type of fridge the user has.
• For the type, the accepted values, followed by their quantity as integers, are: FRIDGE, FREEZER, FRIDGE_AND_FREEZER, SMALL_ELECTRIC_WINE_CELLAR or LARGE_ELECTRIC_WINE_CELLAR.
TUMBLE DRYER
In case of the tumble dryer, we want to know how many units the user has and if they use the appliance all year long or only for some seasons.
• For the type, the accepted values are: CONDENSER, HEAT_PUMP, VENTED or I_DONT_KNOW. Followed by each type’s quantity.
• The usage_types several options can be clicked, this property is a list, and the accepted values are: AUTUMN, SPRING, SUMMER and/or WINTER.
OTHER APPLIANCES
Finally, we want to know if the user has any other appliances that are not shown in our list. This helps us to identify the most common ones in order to add them in the future to our disaggregation library. Please have in mind that any appliance added here won’t be displayed on the disaggregation results.
• For the name, any text value can be accepted.
The current version of the appliance list is 1.0.
Meter geolocation
It is important for us to know where the smart meter is located, that way we can have weather information that helps us to make most accurate disaggregation.
View geolocation
GET /sensors/{device_id}/metadata/geolocation
Response body
{
"latitude": 51.509865,
"longitude": -0.118092
}
View geoloc info.
Set up geolocation
PUT /sensors/{device_id}/metadata/geolocation
Request body
{
"latitude": 51.509865,
"longitude": -0.118092
}
Geolocation have both fields as mandatory and it must be a valid location.
Disaggregation
The disaggregation is calculated monthly for each calendar month. The calculation takes place at the beginning of each month, using data from the previous month, and the results are available on the third day of the same month. Please note that results are only available for previous months, not the current month.
If there is a need to calculate data from the past for a recently integrated smart meter, disaggregation can be performed for data up to three months old. In such cases, the results will be ready within 24 to 36 hours after the data is received.
Month
GET /sensors/{device_id}/sm/disag/month?year=2024&month=7
Response body
{
"total_consumption": 416951.0,
"disconnection_percentage": 14.3,
"appliances": [
{
"appliance_key": "cooking",
"consumption": 19057.0
},
{
"appliance_key": "electric_vehicle",
"consumption": 197148.0
},
{
"appliance_key": "fridge",
"consumption": 45081.336
},
{
"appliance_key": "lights",
"consumption": 59649.63
},
{
"appliance_key": "others",
"consumption": 12881.073
},
{
"appliance_key": "standby",
"consumption": 53491.2
},
{
"appliance_key": "washing",
"consumption": 29642.76
}
]
}
Returns the disaggregation result for the requested year-month.
Table describing the meaning of the response body:
| Field name | Description |
|---|---|
total_consumption float |
Total consumption of all appliances in Wh |
disconnection_percentage float |
Disconnection percentage of the requested month |
appliances[] array |
It will only contain the appliances found in the disaggregation |
appliances[].appliance_key enum |
Key of the appliance |
appliances[].consumption float |
Energy consumption of the appliance in Wh |
Table describing all disaggregated appliances available:
| Appliance key | Description |
|---|---|
boiler |
The disaggregated consumption from Electric Water Heaters/Boilers |
cooking |
The disaggregated consumption from Electric Stove and/or Oven |
cooking_heating |
The combined disaggregated consumption from Electric Stove/Oven and Electric Heating. Note that this will be valid, instead of the individual Cooking and Heating consumptions, if a user-specified appliance list is not available |
cooling |
The disaggregated consumption from Air Conditioners |
electric_vehicle |
The disaggregated consumption for Electric Vehicle (EV). Note that the EV charging cycle times for each user are also available on this endpoint ADD ENDPOINT HERE |
fridge |
The disaggregated consumption from fridge/freezers and any wine chillers etc |
heating |
The disaggregated consumption from Electric Heating. Note that this may also include the disaggregated consumption from any AC that is being used for heating during the winter months |
lights |
The disaggregated consumption from lights and low-power electronic appliances (e.g. TVs, sounds systems, security cameras etc) |
others |
This is the consumption that is not assigned to any of the currently disaggregated appliances and may be (partly) attributable to specialized appliances present in the home, such as Jacuzzis, heat pumps, etc |
standby |
The disaggregated consumption due to appliances operating on Standby/Always ON mode around the house |
washing |
The combined disaggregated consumption from Washing Machine, Dishwasher and Tumble Dryer (as relevant to each home). Note that the separated consumptions for Washing Machine, Dishwasher and Tumble Dryer will also be made available in the near future |
Month by Weeks
GET /sensors/{device_id}/sm/disag/month/weeks?year=2023&month=9
Response body
{
"total_consumption": 550764.0,
"disconnection_percentage": 14.3,
"weeks": [
{
"from": "2023-09-01",
"to": "2023-09-03",
"total_consumption": 58728.0,
"appliances": [
{
"appliance_key": "cooking",
"consumption": 2559.0
},
{
"appliance_key": "fridge",
"consumption": 7491.9155
},
{
"appliance_key": "lights",
"consumption": 26218.045
},
{
"appliance_key": "others",
"consumption": 11263.99
},
{
"appliance_key": "standby",
"consumption": 7027.2
},
{
"appliance_key": "washing",
"consumption": 4167.85
}
]
},
{
"from": "2023-09-04",
"to": "2023-09-10",
"total_consumption": 104123.0,
"appliances": [
{
"appliance_key": "cooking",
"consumption": 5242.0
},
{
"appliance_key": "fridge",
"consumption": 24488.803
},
{
"appliance_key": "lights",
"consumption": 37118.61
},
{
"appliance_key": "others",
"consumption": 20010.209
},
{
"appliance_key": "standby",
"consumption": 9945.6
},
{
"appliance_key": "washing",
"consumption": 7317.78
}
]
},
{
"from": "2023-09-11",
"to": "2023-09-17",
"total_consumption": 111977.0,
"appliances": [
{
"appliance_key": "cooking",
"consumption": 3511.0
},
{
"appliance_key": "fridge",
"consumption": 8521.274
},
{
"appliance_key": "heating",
"consumption": 15067.439
},
{
"appliance_key": "lights",
"consumption": 39018.01
},
{
"appliance_key": "others",
"consumption": 6457.474
},
{
"appliance_key": "standby",
"consumption": 27763.2
},
{
"appliance_key": "washing",
"consumption": 11125.6
}
]
},
{
"from": "2023-09-18",
"to": "2023-09-24",
"total_consumption": 135707.0,
"appliances": [
{
"appliance_key": "cooking",
"consumption": 3913.0
},
{
"appliance_key": "fridge",
"consumption": 10465.777
},
{
"appliance_key": "lights",
"consumption": 55525.742
},
{
"appliance_key": "others",
"consumption": 25831.58
},
{
"appliance_key": "standby",
"consumption": 26534.4
},
{
"appliance_key": "washing",
"consumption": 13436.5
}
]
},
{
"from": "2023-09-25",
"to": "2023-09-30",
"total_consumption": 140229.0,
"appliances": [
{
"appliance_key": "cooking",
"consumption": 5324.5
},
{
"appliance_key": "fridge",
"consumption": 8700.059
},
{
"appliance_key": "lights",
"consumption": 54820.223
},
{
"appliance_key": "others",
"consumption": 27706.46
},
{
"appliance_key": "standby",
"consumption": 21926.4
},
{
"appliance_key": "washing",
"consumption": 12920.36
}
]
}
]
}
This endpoint follows the same rules as the ones described in the Disaggregation documentation.
Table describing the meaning of the response body:
| Field name | Description |
|---|---|
total_consumption float |
Total consumption of all appliances in Wh for the month |
disconnection_percentage float |
Disconnection percentage of the requested month |
weeks[].from date |
Starting date of the week |
weeks[].to date |
Ending date of the week |
weeks[].total_consumption float |
Total consumption of all appliances in Wh for the week |
weeks[].appliances[] array |
It will only contain the appliances found in the disaggregation |
weeks[].appliances[].appliance_key enum |
Key of the appliance. All keys will be the same as the ones described in the table above. |
weeks[].appliances[].consumption float |
Energy consumption of the appliance in Wh |
Week
GET /sensors/{device_id}/sm/disag/week?startDate=2024-07-08&endDate=2024-07-14
Response body
{
"total_consumption": 416951.0,
"disconnection_percentage": 14.3,
"appliances": [
{
"appliance_key": "cooking",
"consumption": 19057.0
},
{
"appliance_key": "electric_vehicle",
"consumption": 197148.0
},
{
"appliance_key": "fridge",
"consumption": 45081.336
},
{
"appliance_key": "lights",
"consumption": 59649.63
},
{
"appliance_key": "others",
"consumption": 12881.073
},
{
"appliance_key": "standby",
"consumption": 53491.2
},
{
"appliance_key": "washing",
"consumption": 29642.76
}
]
}
Returns the disaggregation result for the requested single week. The startDate and endDate must be a Monday and Sunday, respectively, within the same week.
Example:
startDate=2024-07-08 & endDate=2024-07-14; or
startDate=2024-07-15 & endDate=2024-07-21.
Table describing the meaning of the response body:
| Field name | Description |
|---|---|
total_consumption float |
Total consumption of all appliances in Wh |
disconnection_percentage float |
Disconnection percentage of the requested week |
appliances[] array |
It will only contain the appliances found in the disaggregation |
appliances[].appliance_key enum |
Key of the appliance |
appliances[].consumption float |
Energy consumption of the appliance in Wh |
Table describing all disaggregated appliances available:
| Appliance key | Description |
|---|---|
boiler |
The disaggregated consumption from Electric Water Heaters/Boilers |
cooking |
The disaggregated consumption from Electric Stove and/or Oven |
cooking_heating |
The combined disaggregated consumption from Electric Stove/Oven and Electric Heating. Note that this will be valid, instead of the individual Cooking and Heating consumptions, if a user-specified appliance list is not available |
cooling |
The disaggregated consumption from Air Conditioners |
electric_vehicle |
The disaggregated consumption for Electric Vehicle (EV). Note that the EV charging cycle times for each user are also available on this endpoint ADD ENDPOINT HERE |
fridge |
The disaggregated consumption from fridge/freezers and any wine chillers etc |
heating |
The disaggregated consumption from Electric Heating. Note that this may also include the disaggregated consumption from any AC that is being used for heating during the winter months |
lights |
The disaggregated consumption from lights and low-power electronic appliances (e.g. TVs, sounds systems, security cameras etc) |
others |
This is the consumption that is not assigned to any of the currently disaggregated appliances and may be (partly) attributable to specialized appliances present in the home, such as Jacuzzis, heat pumps, etc |
standby |
The disaggregated consumption due to appliances operating on Standby/Always ON mode around the house |
washing |
The combined disaggregated consumption from Washing Machine, Dishwasher and Tumble Dryer (as relevant to each home). Note that the separated consumptions for Washing Machine, Dishwasher and Tumble Dryer will also be made available in the near future |
Appliance Cycles - Month
GET /sensors/{device_id}/sm/disag/cycles/monthly?year=2024&month=7
Response body
[
{
"appliance_key": "electric_vehicle",
"total_consumption": 1917.0650024414062,
"cycles": [
{
"from": "2024-07-12T00:32:53",
"to": "2024-07-12T04:29:10",
"consumption": 838.8944702148438
},
{
"from": "2024-07-12T20:17:24",
"to": "2024-07-12T22:48:14",
"consumption": 1078.1705322265625
}
]
}
]
Returns the cycles found per appliance for the requested year-month.
Currently, cycles are only implemented for electric_vehicle. Note that cycles for the other appliances will also be made available in the near future.
Table describing the meaning of the response body:
| Field name | Description |
|---|---|
appliance_key enum |
Key of the appliance |
total_consumption float |
Total consumption of all cycles in Wh |
cycles[].from local timestamp |
Start time of the cycle for the period in the device's local time zone |
cycles[].to local timestamp |
End time of the cycle for the period in the device's local time zone |
cycles[].consumption float |
Energy consumption of the cycle in Wh |
Appliance Cycles - Week
GET /sensors/{device_id}/sm/disag/cycles/weekly?startDate=2024-07-08&endDate=2024-07-14
Response body
[
{
"appliance_key": "electric_vehicle",
"total_consumption": 1917.0650024414062,
"cycles": [
{
"from": "2024-07-12T00:32:53",
"to": "2024-07-12T04:29:10",
"consumption": 838.8944702148438
},
{
"from": "2024-07-12T20:17:24",
"to": "2024-07-12T22:48:14",
"consumption": 1078.1705322265625
}
]
}
]
Returns the weekly cycles found per appliance.
Currently, cycles are only implemented for electric_vehicle. Note that cycles for the other appliances will also be made available in the near future.
Following the same rules as described in the Week Disaggregation, the startDate and endDate must be a Monday and Sunday, respectively, within the same week.
Example:
startDate=2024-07-08 & endDate=2024-07-14; or
startDate=2024-07-15 & endDate=2024-07-21.
Table describing the meaning of the response body:
| Field name | Description |
|---|---|
appliance_key enum |
Key of the appliance |
total_consumption float |
Total consumption of all cycles in Wh |
cycles[].from local timestamp |
Start time of the cycle for the period in the device's local time zone |
cycles[].to local timestamp |
End time of the cycle for the period in the device's local time zone |
cycles[].consumption float |
Energy consumption of the cycle in Wh |
Reports
Monthly
GET /sensors/{device_id}/sm/reports/monthly?year=2024&month=7
Response body
{
"day_by_day_metrics": {
"days_without_consumption": 0,
"total_consumed_on_week_days": 10.12829,
"total_consumed_on_weekend_days": 3.57842,
"total_month_consumption": 13.70671,
"average_month_consumption": 0.44215,
"max_month_consumption": {
"day": "2024-07-23",
"total_consumption": 0.46071,
"weekend": false
},
"min_month_consumption": {
"day": "2024-07-24",
"total_consumption": 0.40534,
"weekend": false
},
"days": [
{
"day": "2024-07-01",
"total_consumption": 0.43057,
"weekend": false
},
{
"day": "2024-07-02",
"total_consumption": 0.43952,
"weekend": false
},
{
"day": "2024-07-03",
"total_consumption": 0.43846,
"weekend": false
},
{
"day": "2024-07-04",
"total_consumption": 0.43126,
"weekend": false
},
{
"day": "2024-07-05",
"total_consumption": 0.44193,
"weekend": false
},
{
"day": "2024-07-06",
"total_consumption": 0.44847,
"weekend": true
},
{
"day": "2024-07-07",
"total_consumption": 0.43929,
"weekend": true
},
{
"day": "2024-07-08",
"total_consumption": 0.43057,
"weekend": false
},
{
"day": "2024-07-09",
"total_consumption": 0.43952,
"weekend": false
},
{
"day": "2024-07-10",
"total_consumption": 0.43846,
"weekend": false
},
{
"day": "2024-07-11",
"total_consumption": 0.43126,
"weekend": false
},
{
"day": "2024-07-12",
"total_consumption": 0.44193,
"weekend": false
},
{
"day": "2024-07-13",
"total_consumption": 0.44847,
"weekend": true
},
{
"day": "2024-07-14",
"total_consumption": 0.43929,
"weekend": true
},
{
"day": "2024-07-15",
"total_consumption": 0.43057,
"weekend": false
},
{
"day": "2024-07-16",
"total_consumption": 0.43952,
"weekend": false
},
{
"day": "2024-07-17",
"total_consumption": 0.43846,
"weekend": false
},
{
"day": "2024-07-18",
"total_consumption": 0.43126,
"weekend": false
},
{
"day": "2024-07-19",
"total_consumption": 0.44193,
"weekend": false
},
{
"day": "2024-07-20",
"total_consumption": 0.44847,
"weekend": true
},
{
"day": "2024-07-21",
"total_consumption": 0.43929,
"weekend": true
},
{
"day": "2024-07-22",
"total_consumption": 0.43057,
"weekend": false
},
{
"day": "2024-07-23",
"total_consumption": 0.43952,
"weekend": false
},
{
"day": "2024-07-24",
"total_consumption": 0.43846,
"weekend": false
},
{
"day": "2024-07-25",
"total_consumption": 0.43126,
"weekend": false
},
{
"day": "2024-07-26",
"total_consumption": 0.44193,
"weekend": false
},
{
"day": "2024-07-27",
"total_consumption": 0.44847,
"weekend": true
},
{
"day": "2024-07-28",
"total_consumption": 0.43929,
"weekend": true
},
{
"day": "2024-07-29",
"total_consumption": 0.43057,
"weekend": false
},
{
"day": "2024-07-30",
"total_consumption": 0.43952,
"weekend": false
},
{
"day": "2024-07-31",
"total_consumption": 0.43846,
"weekend": false
}
]
},
"disaggregation_metrics": {
"total_consumption": 13706.82,
"disconnection_percentage": 14.3,
"appliances": [
{
"appliance_key": "cooling",
"consumption": 0
},
{
"appliance_key": "fridge",
"consumption": 5413.5107
},
{
"appliance_key": "heating",
"consumption": 0
},
{
"appliance_key": "lights",
"consumption": 2918.9485
},
{
"appliance_key": "others",
"consumption": 2.2737368e-13
},
{
"appliance_key": "standby",
"consumption": 5374.361
},
{
"appliance_key": "washing",
"consumption": 0
}
]
},
"carbon_footprint": {
"kgco2": 7.11378249,
"trees": 3.803064
},
"version": 1
}
Returns the monthly disaggregation result for the requested month.
Table describing the meaning of the response body:
| Field name | Description |
|---|---|
day_by_day_metrics.days_without_consumption int |
Total days without any consumption |
day_by_day_metrics.total_consumed_on_week_days float |
Total energy consumption of weekdays in Wh |
day_by_day_metrics.total_consumed_on_weekend_days float |
Total energy consumption of weekend days in Wh |
day_by_day_metrics.total_month_consumption float |
Total energy consumption of the month in Wh |
day_by_day_metrics.average_month_consumption float |
Average of the month's energy consumption in Wh |
day_by_day_metrics.max_month_consumption.day string |
Day of the most consumption in the month (format: YYYY-MM-DD) |
day_by_day_metrics.max_month_consumption.total_consumption float |
Total energy consumption in Wh of the day with most consumption |
day_by_day_metrics.max_month_consumption.weekend boolean |
True if the day with most consumption is a weekend day |
day_by_day_metrics.min_month_consumption.day string |
Day of the lowest consumption in the month (format: YYYY-MM-DD) |
day_by_day_metrics.min_month_consumption.total_consumption float |
Total energy consumption in Wh of the day with lowest consumption |
day_by_day_metrics.min_month_consumption.weekend boolean |
True if the day with lowest consumption is a weekend day |
day_by_day_metrics.days array |
It will contain the day by day data of the month |
day_by_day_metrics.days[].day string |
Day of the the month (format: YYYY-MM-DD) |
day_by_day_metrics.days[].total_consumption float |
Total energy consumption in Wh of the day |
day_by_day_metrics.days[].weekend boolean |
True if the day is a weekend day |
disaggregation_metrics.total_consumption float |
Total energy consumption in Wh |
disaggregation_metrics.disconnection_percentage float |
Disconnection percentage of the requested month |
disaggregation_metrics.appliances[] array |
It will only contain the appliances found in the disaggregation |
disaggregation_metrics.appliances[].appliance_key enum |
Key of the appliance |
disaggregation_metrics.appliances[].consumption float |
Energy consumption of the appliance in Wh |
carbon_footprint.kgco2 float |
Calculation of CO2 emission in kg |
carbon_footprint.trees float |
How many trees would be needed to absorb the amount of CO2 emmited |
version int |
Version of the report |
Table describing all disaggregated appliances available:
| Appliance key | Description |
|---|---|
boiler |
The disaggregated consumption from Electric Water Heaters/Boilers |
cooking |
The disaggregated consumption from Electric Stove and/or Oven |
cooking_heating |
The combined disaggregated consumption from Electric Stove/Oven and Electric Heating. Note that this will be valid, instead of the individual Cooking and Heating consumptions, if a user-specified appliance list is not available |
cooling |
The disaggregated consumption from Air Conditioners |
electric_vehicle |
The disaggregated consumption for Electric Vehicle (EV). Note that the EV charging cycle times for each user are also available on this endpoint ADD ENDPOINT HERE |
fridge |
The disaggregated consumption from fridge/freezers and any wine chillers etc |
heating |
The disaggregated consumption from Electric Heating. Note that this may also include the disaggregated consumption from any AC that is being used for heating during the winter months |
lights |
The disaggregated consumption from lights and low-power electronic appliances (e.g. TVs, sounds systems, security cameras etc) |
others |
This is the consumption that is not assigned to any of the currently disaggregated appliances and may be (partly) attributable to specialized appliances present in the home, such as Jacuzzis, heat pumps, etc |
standby |
The disaggregated consumption due to appliances operating on Standby/Always ON mode around the house |
washing |
The combined disaggregated consumption from Washing Machine, Dishwasher and Tumble Dryer (as relevant to each home). Note that the separated consumptions for Washing Machine, Dishwasher and Tumble Dryer will also be made available in the near future |
Weekly
GET /sensors/{device_id}/sm/reports/weekly?startDate=2024-07-08&endDate=2024-07-14
Response body
{
"day_by_day_metrics": {
"days_without_consumption": 0,
"total_consumed_on_week_days": 10.12829,
"total_consumed_on_weekend_days": 3.57842,
"total_week_consumption": 13.70671,
"average_week_consumption": 0.44215,
"max_week_consumption": {
"day": "2024-07-11",
"total_consumption": 0.46071,
"weekend": false
},
"min_week_consumption": {
"day": "2024-07-13",
"total_consumption": 0.40534,
"weekend": true
},
"days": [
{
"day": "2024-07-08",
"total_consumption": 0.43057,
"weekend": false
},
{
"day": "2024-07-09",
"total_consumption": 0.43952,
"weekend": false
},
{
"day": "2024-07-10",
"total_consumption": 0.43846,
"weekend": false
},
{
"day": "2024-07-11",
"total_consumption": 0.43126,
"weekend": false
},
{
"day": "2024-07-12",
"total_consumption": 0.44193,
"weekend": false
},
{
"day": "2024-07-13",
"total_consumption": 0.44847,
"weekend": true
},
{
"day": "2024-07-14",
"total_consumption": 0.43929,
"weekend": true
}
]
},
"disaggregation_metrics": {
"total_consumption": 13706.82,
"disconnection_percentage": 14.3,
"appliances": [
{
"appliance_key": "cooling",
"consumption": 0
},
{
"appliance_key": "fridge",
"consumption": 5413.5107
},
{
"appliance_key": "heating",
"consumption": 0
},
{
"appliance_key": "lights",
"consumption": 2918.9485
},
{
"appliance_key": "standby",
"consumption": 5374.361
}
]
},
"carbon_footprint": {
"kgco2": 7.11378249,
"trees": 3.803064
},
"version": 1
}
This endpoint follows the same rules as the ones described in the Monthly Report documentation.
The following keys within the day_by_day_metrics object have been renamed to differentiate between the month and week endpoints:
total_month_consumption > total_week_consumption
average_month_consumption > average_week_consumption
max_month_consumption > max_week_consumption
min_month_consumption > min_week_consumption