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.

Query parameters use snake_case.

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
`400`	Bad Request: A required query parameter is missing, or the request body is malformed or breaks its limits. The `message` field says which
`401`	Unauthorized: You need to generate the access token (see below)
`403`	Forbidden: Please ensure that the device has sent at least one data point (even a single reading is sufficient) or has metadata set up via the metadata endpoints, so it is correctly registered on the system. If the device was just created, see the Devices section — a token issued before that point will keep returning `403` until you generate a fresh one.
`404`	Not Found: This is not exactly an error. It just means that the resource that you are looking for was not found
`410`	Gone: The endpoint has been retired — see Retired endpoints
`413`	Payload Too Large: The request body is over the accepted size limit
`422`	Unprocessable Content: The payload was rejected on validation, mainly on the metadata endpoints. The `message` field carries the reason
`500`	Internal Server Error: The request could not be completed. On the monthly endpoints it also means no result could be produced for the requested month — see No result for the requested month

If you encounter any other status response codes, then please get in touch with Voltaware.

Errors

Error response

{
  "timestamp": "2026-09-04T12:34:56.789Z",
  "status": 400,
  "id": "MISSING_REQUEST_PARAMETER",
  "message": "Required request parameter year not present"
}

An error is reported by the HTTP status code and, on most responses, by a JSON body with the same four fields:

Field name	Description
`timestamp` ISO timestamp UTC	When the error was produced
`status` integer	The HTTP status code, repeated in the body
`id` string	Stable identifier of the cause. Branch on this, together with the status code, if you need to handle a specific failure
`message` string	Human-readable description of what went wrong. Intended for logs and debugging — do not match on its text, as the wording can change

Not every response carries this body: 401 and 404 are returned with an empty body, and the 403 returned for a device that is not on your account carries a body in a different format. Rely on the status code for those, not on the body.

The id values you can receive:

`id`	Status	When it happens
`MISSING_REQUEST_PARAMETER`	`400`	A required query parameter was not sent. The `message` names it
`INVALID_REQUEST_BODY`	`400`	The request body is not valid JSON, or a required field is missing, blank or over its length limit
`UPSTREAM_REQUEST_REJECTED`	`400`, `422`	The payload was rejected on validation, mainly on the metadata endpoints. The `message` carries the reason
`ENDPOINT_RETIRED`	`410`	The endpoint has been retired — see Retired endpoints
`REQUEST_BODY_TOO_LARGE`	`413`	The request body is over the accepted size limit
`INTERNAL_ERROR`	`500`	The request could not be completed
`NO_DISAGGREGATION_STATUS_RECORDED`, `DISAGGREGATION_SUCCESS_WITHOUT_RESULT`, or a disaggregation status name	`500`	No result could be produced for the requested month — see No result for the requested month
`REPORTING_DASHBOARD_LOOKUP_FAILED`	`500`	The reason a month has no result could not be determined

The list is not exhaustive, and new ids may be added: treat an id you do not recognise as an internal failure and rely on the status code.

Each endpoint section below lists the errors specific to that endpoint.

No result for the requested month

These endpoints do not answer 404 when there is no result for the requested month:

GET /sensors/{device_id}/sm/disag/month
GET /sensors/{device_id}/sm/reports/monthly
GET /sensors/{device_id}/sm/insights/monthly

Error response

{
  "timestamp": "2026-09-04T12:34:56.789Z",
  "status": 500,
  "id": "MONTHLY_AGGREGATOR_EPOCHS_NOT_FOUND",
  "message": "No disaggregation result for sensor SENSOR_123 [2024-07]: No weekly disaggregation results existed for the days of the month, so there was nothing to aggregate."
}

They answer 500 instead, and the id says why no result could be produced:

`id`	What it means
`NO_DISAGGREGATION_STATUS_RECORDED`	No result was produced for that month and no failure was recorded for it. Usually the device is not registered for disaggregation
`DISAGGREGATION_SUCCESS_WITHOUT_RESULT`	Disaggregation completed for that month but wrote no result
`MONTHLY_AGGREGATOR_EPOCHS_NOT_FOUND`	No disaggregation results existed for the days of that month, so there was nothing to aggregate into a monthly result. This is the usual outcome when the device was not disaggregated during the month — for example a home registered as having solar generation whose production could not be estimated, which blocks the run
`MONTHLY_AGGREGATOR_MISMATCH_ERROR`	The monthly figures failed their consistency check: the appliance consumptions did not match the total consumption, so the month was rejected instead of being published
`MONTHLY_AGGREGATOR_EXCEPTION`, `UNEXPECTED_EXCEPTION`	The monthly run failed with an internal error

Any other id on these endpoints is an internal failure on our side.

Retrying the same request will keep returning 500 until the month is reprocessed. Please get in touch with Voltaware with the id, the message and the device id.

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.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`	The request body is not valid JSON, or a credential field is missing, blank or over its length limit
`401`	The credentials were rejected, or `grant_type` is not `client_credentials`. Returned with an empty body
`413`	The request body is over the accepted size limit

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
}

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`	The request body is not valid JSON, or a field is missing, blank or over its length limit
`401`	The refresh token was rejected, or `grant_type` is not `refresh_token`. Returned with an empty body
`413`	The request body is over the accepted size limit

Devices

Provides detailed information about devices.

Device lookups are served from a token-bound cache. If a device was just created — by sending its first MQTT reading or by setting up its metadata — an access token issued before that point won't see it yet, and requests like GET /sensors/{device_id} will keep returning `403` for it. Generate a freshly issued access token after the device is created to pick up the change.

List all devices

HTTP request

GET /sensors

Request headers

Authorization: Bearer access_token

Response body

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.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`401`	The access token is missing, invalid or expired. Returned with an empty body

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

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`404`	No device with that id is available to your account. Returned with an empty body

Most recent readings

For a set of devices

HTTP request

POST /sensors/readings/latest

Request headers

Authorization: Bearer access_token
Content-Type: application/json

Request body

{
  "device_ids": [
    "SENSOR_123",
    "SENSOR_456"
  ]
}

Response body

{
  "device_dates": [
    {
      "device_id": "device-001",
      "latest_date": "2026-06-10"
    },
    {
      "device_id": "device-002",
      "latest_date": "2026-06-11"
    },
    {
      "device_id": "device-003",
      "latest_date": "2026-06-12"
    }
  ]
}

Field name	Description
`device_ids` array[string], required	Maximum of 10,000 items. If the list exceeds this limit, the API returns HTTP status code `413`.

This endpoint returns the most recent date for which readings are available for the devices specified in the request.

Any device that does not exist in our system will return with a null latest_date.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`	The request body is not valid JSON
`401`	The access token is missing, invalid or expired. Returned with an empty body
`404`	No readings are available for any of the requested devices. Returned with an empty body
`413`	The request body is over the accepted size limit

For all devices

HTTP request

GET /sensors/readings/latest?last_device_id=&page_size=

Request headers

Authorization: Bearer access_token

Response body

{
  "device_dates": [
    {
      "device_id": "device-001",
      "latest_date": "2026-06-10"
    },
    {
      "device_id": "device-002",
      "latest_date": "2026-06-11"
    },
    {
      "device_id": "device-003",
      "latest_date": "2026-06-12"
    }
  ]
}

last_device_id optional: because this endpoint is paginated, omit this parameter or set it to null in the inicial request.

page_size: optional, the default page size is 1000. The maximum allowed page size is 10,000.

This endpoint returns the most recent day for which readings are availabe for all devices in your account.

Results are paginated and returned in ascending order by device id.

To retrieve the next page, pass the last device id from the previous response as the last_device_id parameter. Once the final page has been reached, subsequent requests will return an empty device_dates array.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`401`	The access token is missing, invalid or expired. Returned with an empty body
`404`	No readings are available. Returned with an empty body

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. We do disaggregate devices at properties that produce their own energy (solar panels, batteries...), but that production may affect the accuracy of the disaggregation, so those results are returned with warnings in the warnings array — see the Disaggregation section for the possible warning ids.

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.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`404`	No property details have been set up for this device. Returned with an empty body

Set up property details

PUT /sensors/{device_id}/metadata/property

Request body for home_type house

{
  "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_type office, 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:

If the device sent not exists, it will be created, then you need to reconnect to the API

In case the property_type is OFFICE, COMMERCIAL, INDUSTRY, the following are the fields needed in the request body.

Field name	Description
`property_type` string (enum), required	`OFFICE`, `COMMERCIAL`, `INDUSTRY`
`power_generator_source` string (enum), required	`SOLAR`, `HYDROELECTRICITY`, `WIND`, `BATTERY`, `OTHER`, `NONE`, `UNKNOWN` — see Power generation below for what each value means and what it changes
`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`, `UNKNOWN` — see Power generation below for what each value means and what it changes
`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`

Power generation

power_generator_source records whether the property generates its own electricity, and from what. It does more than describe the property: it decides how the disaggregation treats the home's generation — whether the home is handled as a solar (PV) home, whether we look to its readings to find out, and what the monthly result reports under site_setup.pv.

Value	Meaning	What we do with it
`SOLAR`	The property has solar panels	Treated as a solar home from the start. Its production is estimated as part of the disaggregation, and `site_setup.pv` reports `detected: true` with `detection_source: DECLARED`. The readings cannot change this answer; only updating this field can. When a month's production cannot be estimated, that month has no result — see `MONTHLY_AGGREGATOR_EPOCHS_NOT_FOUND` under Errors
`BATTERY`	The property has battery storage, normally alongside solar panels	Treated the same way as `SOLAR`
`HYDROELECTRICITY`	The property generates from a hydroelectric source	Recorded as generating power, but not solar power. The home is not treated as a solar home and we do not look to its readings for solar generation; `site_setup.pv` reports `detected: false`
`WIND`	The property generates from wind	As `HYDROELECTRICITY`
`OTHER`	The property generates from a source not listed here	As `HYDROELECTRICITY`
`NONE`	The property generates no electricity of its own	Solar generation is ruled out. The home is never treated as a solar home, we do not look to its readings for solar generation, and `site_setup.pv` reports `detected: false`. If the readings show generation regardless, the result still follows your answer and the month carries the `PV_DECLARATION_CONFLICT` warning
`UNKNOWN`	You do not know whether the property generates electricity	The question is left open and the readings answer it. We look for solar generation in the device's data every month — from its export (feed-in) readings where they exist, otherwise from its consumption profile alone — and treat the home as a solar home when it is found. `site_setup.pv` then reports `detected: true` with `METERED` or `INFERRED`, `false` when nothing was found, or `null` for a month that could not be assessed

NONE or UNKNOWN?

These two are the ones most often confused. NONE is an answer; UNKNOWN is the absence of one.

Question	`NONE`	`UNKNOWN`
What you are telling us	This property generates nothing	You do not know whether it generates
Do we look for solar generation in the readings?	No — your answer is final	Yes — every month, from whatever readings the month has
Can the answer change over time?	Only when you update this field	Yes — it follows the data, and can differ from one month to the next
`site_setup.pv.detected`	`false`	`true`, `false` or `null`, per month
`site_setup.pv.detection_source`	`null`	`METERED` or `INFERRED` when found, otherwise `null`
If the readings show generation anyway	The month carries `PV_DECLARATION_CONFLICT` and the result still says no solar	The home is treated as a solar home
When to use it	Only when you know the property has no generation of any kind	Whenever you are not sure — this is the value to default to

Send UNKNOWN whenever you are not certain whether a property generates power. Use NONE only when you know it does not: it switches solar detection off for the device, and a wrong NONE is only ever surfaced as a warning, never corrected.

Property details and the solar property are one record

power_generator_source and the power_generation flag of the Solar Property endpoint describe the same fact from two sides, and writing either one updates the other:

Setting power_generator_source decides what the solar property then reads back: power_generation is true for SOLAR and BATTERY, false for HYDROELECTRICITY, WIND, OTHER and NONE, and null for UNKNOWN. Only SOLAR and BATTERY keep a capacity and mounting_structure; for any other source both read back as null.
Setting power_generation through the solar property endpoint records the source as SOLAR.

If a device has solar panels and you know their capacity, set up the property details first and the solar property second, so the capacity lands on a record that already says SOLAR.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`, `422`	The payload was rejected. The `message` field carries the reason reported by the service that validated it
`401`	The access token is missing, invalid or expired. Returned with an empty body
`413`	The request body is over the accepted size limit

This endpoint does not answer 403: if the device is not on your account yet, it is created by the request, and you then need to generate a fresh access token before reading it back — see the Devices section.

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.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`404`	No appliance list has been set up for this device. Returned with an empty body

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.

If the device sent not exists, it will be created, then you need to reconnect to the API

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.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`, `422`	The payload was rejected. The `message` field carries the reason reported by the service that validated it
`401`	The access token is missing, invalid or expired. Returned with an empty body
`413`	The request body is over the accepted size limit

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.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`404`	No geolocation has been set up for this device. Returned with an empty body

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.

If the device sent not exists, it will be created, then you need to reconnect to the API

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`, `422`	The payload was rejected. The `message` field carries the reason reported by the service that validated it
`401`	The access token is missing, invalid or expired. Returned with an empty body
`413`	The request body is over the accepted size limit

Solar Property

View solar property

GET /sensors/{device_id}/metadata/property/solar

Response body

{
    "power_generation": true,
    "capacity": 14.5,
    "mounting_structure": "ROOF_MOUNT",
    "version": "1.0"
}

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`404`	No solar property information has been set up for this device. Returned with an empty body

Set up solar property

PUT /sensors/{device_id}/metadata/property/solar

Request body

{
    "power_generation": true,
    "capacity": 14.5,
    "mounting_structure": "GROUND_MOUNT",
    "version": "1.0"
}

Field name	Description
`power_generation` boolean, required	Mandatory boolean flag
`capacity` number, nullable	Nullable number between 1 and 50, in increments of 0.1 (e.g. `14.5`, not `14.53`)
`mounting_structure` string (enum), nullable	Nullable enum: `ROOF_MOUNT` or `GROUND_MOUNT`
`version` string, required	The current `version` of the solar property information is `1.0`

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`, `422`	The payload was rejected. The `message` field carries the reason reported by the service that validated it
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`413`	The request body is over the accepted size limit

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,
  "missing_timestamps_percentage": 14.3,
  "site_setup": {
    "pv": {
      "detected": true,
      "detection_source": "METERED"
    },
    "battery": {
      "detected": true,
      "detection_source": "METERED"
    }
  },
  "appliances": [
    {
      "appliance_key": "cooking",
      "consumption": 19057.0
    },
    {
      "appliance_key": "electric_vehicle",
      "consumption": 197148.0
    },
    {
      "appliance_key": "fridge",
      "consumption": 45081.336
    },
    {
      "appliance_key": "lights_electronics",
      "consumption": 59649.63
    },
    {
      "appliance_key": "others",
      "consumption": 12881.073
    },
    {
      "appliance_key": "standby",
      "consumption": 53491.2
    },
    {
      "appliance_key": "washing",
      "consumption": 29642.76
    }
  ],
  "warnings": [
    {
      "id": "BATTERY_DETECTED",
      "description": "Battery Detected: home has storage. Charge and discharge are not separated from load, so appliance estimates may be affected."
    },
    {
      "id": "INCOMPLETE_MONTH",
      "description": "Incomplete Month: 20 days of readings data. Expected 31 days of readings."
    }
  ]
}

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
`missing_timestamps_percentage` float	Percentage of the month's expected meter readings that were not received
`site_setup` object	What the month's readings show about the home's own energy equipment — see Site setup below
`site_setup.pv.detected` boolean, nullable	Whether the home was found to generate solar energy. `null` when this could not be assessed for the month
`site_setup.pv.detection_source` string (enum), nullable	How solar generation was established. `null` whenever `detected` is not `true`
`site_setup.battery.detected` boolean, nullable	Whether the home was found to have battery storage. `null` when this could not be assessed for the month
`site_setup.battery.detection_source` string (enum), nullable	How battery storage was established. `null` whenever `detected` is not `true`
`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
`warnings[]` array	Any data-quality or consistency warnings detected for the month. Empty if none apply
`warnings[].id` enum	Identifier of the warning type
`warnings[].description` string	Human-readable detail for this specific occurrence of the warning

Site setup

site_setup reports what is known about the home's own energy equipment for that month. A result comes either from the month's readings or from the device's recorded property details, which take precedence over the readings — detection_source says which, so a DECLARED value is not monthly measured evidence. Every successful response carries it, for every device: the object and both its fields are always present, never omitted, even when every value is null. A month with no disaggregation result answers 500 with the error body instead — see No result for the requested month.

Each entry answers two separate questions. detected is whether the equipment was found; detection_source is how. They are independent — read them together.

detected has three states, and the third is not a "no":

State	Meaning
`true`	The equipment was found for this month
`false`	The equipment was not established for this month. Usually this means the readings were assessed and gave no indication of it. For `pv` it also covers a home whose solar property details record no solar generation: a recorded answer takes precedence over the readings, so the result is `false` even where the readings suggest otherwise — that case is reported as `PV_DECLARATION_CONFLICT`
`null`	The equipment could not be assessed for this month — this is not the same as `false`, and must not be presented to an end user as an absence

Table describing all possible detection sources:

Detection source	Description
`DECLARED`	Taken from the device's solar property details. A recorded answer is always used in preference to the readings
`METERED`	Established from the export (feed-in) readings received for the home, alongside its consumption readings
`INFERRED`	Established from the consumption readings alone, because no export readings were received for the home
`null`	Returned whenever `detected` is `false` or `null` — there is no positive detection to attribute

DECLARED is never returned for battery: battery storage cannot currently be recorded in the property details, so a battery result always comes from the readings.

A positive battery result always arrives with a warning in the same response, because storage affects how the appliance breakdown should be read: BATTERY_DETECTED when the source is METERED, and PV_BATTERY_EXPORT_DATA_MISSING when it is INFERRED.

battery.detected is null for most homes. Battery storage is only assessed where the readings can support a conclusion, which in practice means homes that generate their own energy. A null here means the question was not answered for this month, not that the home has no battery.

When detection_source is INFERRED, no export readings were received for the home, so the energy it generated and used on site is not visible in the meter data. total_consumption and the appliances breakdown for that month are therefore net of that generation, and will understate what the home actually used. The corresponding PV_EXPORT_DATA_MISSING or PV_BATTERY_EXPORT_DATA_MISSING warning is always present in the same response.

site_setup describes the month it is returned with. A result drawn from the readings reflects the data available for that period, so it can differ between months for the same device — a month with sparser data may return null where a neighbouring month returned true. A DECLARED result does not vary that way: it changes only when the property details change. Treat the object as a per-month observation rather than a permanent record of the home's equipment, and do not carry a value forward from one month to the next.

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
`cooling`	The disaggregated consumption from Air Conditioners
`electric_vehicle`	The disaggregated consumption for Electric Vehicle (EV).
`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_electronics`	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, 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

Table describing all possible warnings for this endpoint:

Warning id	Description
`BATTERY_DETECTED`	The home was found to have battery storage. Battery charge and discharge are not separated from household load, so the appliance estimates for the month may be affected
`INCOMPLETE_MONTH`	The requested month has fewer days of data than the full calendar month - the result reflects only the days that were available
`OUTLIER_CONSUMPTION`	Outlier readings were detected in the month's meter data and their consumption was set to zero before the disaggregation, so the affected periods may be under-reported in the result
`PV_BATTERY_EXPORT_DATA_MISSING`	The home generates solar energy and has battery storage, but no export-to-grid data was received for the month, so the energy exported to the grid is not reflected in the result
`PV_DECLARATION_CONFLICT`	The device's solar property details record that this home does not generate solar energy, but the month's readings indicate that it does. The result follows the recorded property details — review the solar property set up for this device
`PV_EXPORT_DATA_MISSING`	The home generates solar energy, but no export-to-grid data was received for the month, so the energy exported to the grid is not reflected in the result
`TOTAL_CONSUMPTION_INCONSISTENCY`	The sum of the disaggregated appliance consumptions diverges from the total consumption received for the month

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`	The `year` or `month` query parameter is missing, or is not a number
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`500`	No result could be produced for the requested month — see No result for the requested month. These endpoints never answer `404` for an empty month

A month with no disaggregation result is answered with 500, not 404. Retrying the same request will keep failing until the month is reprocessed.

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:30:00",
        "to": "2024-07-12T04:45:00",
        "consumption": 838.8944702148438
      },
      {
        "from": "2024-07-12T20:00:00",
        "to": "2024-07-12T22:45:00",
        "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

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`	The `year` or `month` query parameter is missing, or is not a number
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`404`	No appliance cycles are available for the requested month. Returned with an empty body

Solar

The Solar endpoints expose PV (photovoltaic) monitoring metrics for devices with solar panels. They return aggregated energy figures for a given period — capacity, production, consumption, import and export — derived from interval-level PV data. These same metrics are also included as pv_metrics in the Monthly Report response.

Both endpoints share the same response structure. Values are in kWh, except capacity which is in kW.

Daily

GET /sensors/{device_id}/sm/solar/daily?day=2024-07-10

Query parameter	Description
`day` string, required	The date to retrieve data for (format: `YYYY-MM-DD`)

Response body

{
  "capacity": 8.53,
  "production": 12.45,
  "consumption": 18.72,
  "import": 6.27,
  "export": 0.0
}

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`	The `day` query parameter is missing or is not a valid `YYYY-MM-DD` date
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`404`	No solar result is available for the requested day. Returned with an empty body

Monthly

GET /sensors/{device_id}/sm/solar/monthly?year=2024&month=7

Query parameter	Description
`year` int, required	The year of the requested month (format: `YYYY`)
`month` int, required	The month number (1–12)

Response body

{
  "capacity": 8.53,
  "production": 312.18,
  "consumption": 487.63,
  "import": 175.45,
  "export": 37.12
}

Table describing the meaning of the response body:

Field name	Description
`capacity` float	PV system capacity in kW — constant for the device, taken from the first available interval
`production` float	Total energy produced by the solar panels in kWh for the requested period
`consumption` float	Total energy consumed by the household in kWh for the requested period
`import` float	Total energy imported from the grid in kWh for the requested period
`export` float	Total energy exported to the grid in kWh for the requested period

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`	The `year` or `month` query parameter is missing, or is not a number
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`404`	No solar result is available for the requested month. Returned with an empty body

Insights

The insights include a VoltaScore for each of the appliances present within the home (except EV), as well as recommendations for the two appliances with the lowest score.

VoltaScore is a measure of how the consumption of an appliance compares to that of the peers for a given month. For instance, a score of 86 for the boiler means that the home’s boiler consumption was lower than 86% of the homes within the peer cluster. Therefore, a higher score indicates a more efficient appliance usage pattern.

As part of the insights, personalized recommendations are also provided for the two appliances with the lowest score for a given month. They include advice to help reduce the appliance consumption, increase efficiency and in turn improve the appliance’s future VoltaScore.

Monthly Insights

GET /sensors/{device_id}/sm/insights/monthly?year=2025&month=4

Response body

{
  "volta_score": {
    "total_score": 22,
    "appliances": [
      {
        "appliance_key": "standby",
        "score": 75
      },
      {
        "appliance_key": "fridge",
        "score": 35
      },
      {
        "appliance_key": "lights_electronics",
        "score": 24
      },
      {
        "appliance_key": "cooking",
        "score": 1
      },
      {
        "appliance_key": "washing",
        "score": 1
      }
    ]
  },
  "personalized_recommendations": [
    "Your Cooking consumption this month was higher than 99% of your peers. Consider using the microwave whenever possible as it is more energy efficient compared to stove/oven.",
    "Your Washing/Laundry consumption this month was higher than 99% of your peers. Consider using the ECO mode and running your washing appliances during the off-peak hours."
  ]
}

Returns the insights result for the requested year-month.

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`	The `year` or `month` query parameter is missing, or is not a number
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`500`	No result could be produced for the requested month — see No result for the requested month. These endpoints never answer `404` for an empty month

Reports

Monthly

GET /sensors/{device_id}/sm/reports/monthly?year=2024&month=7

Response body

{
  "day_by_day_metrics": {
    "days_without_consumption": 2,
    "total_month_consumption": 617.80578, "average_month_consumption": 19.92921,
    "total_consumed_on_week_days": 461.93113,
    "total_consumed_on_weekend_days": 155.87464,
    "max_month_consumption": {
      "day": "2025-01-20",
      "total_consumption": 24.23524,
      "weekend": false
    },
    "min_month_consumption": {
      "day": "2025-01-08",
      "total_consumption": 17.17940,
      "weekend": false
    },
    "days": [
      {
        "day": "2025-01-01",
        "total_consumption": 23.13719,
        "weekend": false
      },
      {
        "day": "2025-01-02",
        "total_consumption": 18.30831,
        "weekend": false
      },
      {
        "day": "2025-01-03",
        "total_consumption": 21.91284,
        "weekend": false
      },
      {
        "day": "2025-01-04",
        "total_consumption": 20.93369,
        "weekend": true
      },
      {
        "day": "2025-01-05",
        "total_consumption": 22.75877,
        "weekend": true
      },
      {
        "day": "2025-01-06",
        "total_consumption": 20.35235,
        "weekend": false
      },
      {
        "day": "2025-01-07",
        "total_consumption": 20.94305,
        "weekend": false
      },
      {
        "day": "2025-01-08",
        "total_consumption": 17.17940,
        "weekend": false
      },
      {
        "day": "2025-01-09",
        "total_consumption": 21.48208,
        "weekend": false
      },
      {
        "day": "2025-01-10",
        "total_consumption": 20.95415,
        "weekend": false
      },
      {
        "day": "2025-01-11",
        "total_consumption": 21.95650,
        "weekend": true
      },
      {
        "day": "2025-01-12",
        "total_consumption": 23.67769,
        "weekend": true
      },
      {
        "day": "2025-01-13",
        "total_consumption": 20.19603,
        "weekend": false
      },
      {
        "day": "2025-01-14",
        "total_consumption": 21.03453,
        "weekend": false
      },
      {
        "day": "2025-01-15",
        "total_consumption": 21.26460,
        "weekend": false
      },
      {
        "day": "2025-01-16",
        "total_consumption": 24.14290,
        "weekend": false
      },
      {
        "day": "2025-01-17",
        "total_consumption": 18.61118,
        "weekend": false
      },
      {
        "day": "2025-01-19",
        "total_consumption": 20.07237,
        "weekend": true
      },
      {
        "day": "2025-01-20",
        "total_consumption": 24.23524,
        "weekend": false
      },
      {
        "day": "2025-01-21",
        "total_consumption": 21.28436,
        "weekend": false
      },
      {
        "day": "2025-01-22",
        "total_consumption": 20.99447,
        "weekend": false
      },
      {
        "day": "2025-01-23",
        "total_consumption": 21.10923,
        "weekend": false
      },
      {
        "day": "2025-01-24",
        "total_consumption": 19.90616,
        "weekend": false
      },
      {
        "day": "2025-01-25",
        "total_consumption": 22.83493,
        "weekend": true
      },
      {
        "day": "2025-01-26",
        "total_consumption": 23.64066,
        "weekend": true
      },
      {
        "day": "2025-01-27",
        "total_consumption": 21.77656,
        "weekend": false
      },
      {
        "day": "2025-01-28",
        "total_consumption": 21.08660,
        "weekend": false
      },
      {
        "day": "2025-01-29",
        "total_consumption": 20.17186,
        "weekend": false
      },
      {
        "day": "2025-01-30",
        "total_consumption": 21.84792,
        "weekend": false
      }
    ]
  },
  "disaggregation_metrics": {
    "total_consumption": 617805.75,
    "missing_timestamps_percentage": 6.451613,
    "appliances": [
      {
        "appliance_key": "fridge",
        "consumption": 38069.938
      },
      {
        "appliance_key": "lights_electronics",
        "consumption": 108955.625
      },
      {
        "appliance_key": "others",
        "consumption": 156043.39
      },
      {
        "appliance_key": "standby",
        "consumption": 18946.316
      },
      {
        "appliance_key": "electric_vehicle",
        "consumption": 8505.0
      },
      {
        "appliance_key": "washing",
        "consumption": 133071.8
      },
      {
        "appliance_key": "cooking",
        "consumption": 162718.7
      }
    ],
    "warnings": [
      {
        "id": "INCOMPLETE_MONTH",
        "description": "Incomplete Month: 20 days of readings data. Expected 31 days of readings."
      }
    ]
  },
  "insights": {
    "volta_score": {
      "total_score": 22,
      "appliances": [
        {
          "appliance_key": "washing",
          "score": 1
        },
        {
          "appliance_key": "fridge",
          "score": 35
        },
        {
          "appliance_key": "standby",
          "score": 75
        },
        {
          "appliance_key": "cooking",
          "score": 1
        },
        {
          "appliance_key": "lights_electronics",
          "score": 24
        }
      ]
    },
    "personalized_recommendations": [
      "Your Cooking consumption this month was higher than 99% of your peers. Consider using the microwave whenever possible as it is more energy efficient compared to stove/oven.",
      "Your Washing/Laundry consumption this month was higher than 99% of your peers. Consider using the ECO mode and running your washing appliances during the off-peak hours."
    ]
  },
  "carbon_footprint": {
    "kgco2": 320.64120,
    "trees": 171.4164
  },
  "version": 1,
  "cycles": [
    {
      "appliance_key": "electric_vehicle",
      "total_consumption": 8505.0,
      "cycles": [
        {
          "from": "2025-01-12T23:30:00",
          "to": "2025-01-13T01:30:00",
              "consumption": 6352.0
        },
        {
          "from": "2025-01-18T06:15:00",
          "to": "2025-01-18T07:15:00",
          "consumption": 2153.0
        }
      ]
    }
  ],
  "pv_metrics": {
    "capacity": 9.99,
    "production": 78.34,
    "consumption": 2307.63,
    "import": 2253.57,
    "export": 37.12,
  }
}

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.missing_timestamps_percentage` float	Percentage of the month's expected meter readings that were not received
`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
`disaggregation_metrics.warnings[]` array	Any data-quality or consistency warnings detected for the period. Empty if none apply. See the Disaggregation section for the possible warning ids
`disaggregation_metrics.warnings[].id` enum	Identifier of the warning type
`disaggregation_metrics.warnings[].description` string	Human-readable detail for this specific occurrence of the warning
`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
`pv_metrics` object	PV monitoring metrics — only present for devices with solar panels configured
`pv_metrics.capacity` float	PV system capacity in kW — constant for the device, taken from the first available interval
`pv_metrics.production` float	Total energy produced by the solar panels in kWh for the requested period
`pv_metrics.consumption` float	Total energy consumed by the household in kWh for the requested period
`pv_metrics.import` float	Total energy imported from the grid in kWh for the requested period
`pv_metrics.export` float	Total energy exported to the grid in kWh for the requested period

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
`cooling`	The disaggregated consumption from Air Conditioners
`electric_vehicle`	The disaggregated consumption for Electric Vehicle (EV).
`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_electronics`	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, 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

Errors for this endpoint — see Errors for the response body:

Status	When it happens
`400`	The `year` or `month` query parameter is missing, or is not a number
`401`	The access token is missing, invalid or expired. Returned with an empty body
`403`	The device is not on your account, or is not registered on the system yet — see the Devices section
`500`	No result could be produced for the requested month — see No result for the requested month. These endpoints never answer `404` for an empty month

Retired endpoints

Weekly results have been retired. The endpoints below answer 410 Gone with the id ENDPOINT_RETIRED and the message Weekly results have been retired. Use the monthly endpoints under /sensors/{sensor_id}/sm/.

Retired endpoint	Replacement
`GET /sensors/{device_id}/sm/disag/week`	`GET /sensors/{device_id}/sm/disag/month`
`GET /sensors/{device_id}/sm/disag/cycles/weekly`	`GET /sensors/{device_id}/sm/disag/cycles/monthly`
`GET /sensors/{device_id}/sm/reports/weekly`	`GET /sensors/{device_id}/sm/reports/monthly`
`GET /sensors/{device_id}/sm/solar/weekly`	`GET /sensors/{device_id}/sm/solar/monthly`
`GET /sensors/{device_id}/sm/insights/weekly`	`GET /sensors/{device_id}/sm/insights/monthly`

Authentication and authorization still apply to these URIs: a request with no access token is still 401, and a request for a device that is not on your account is still 403.