Consumption disaggregation

Overview

The Consumption Disaggregation feature provides a breakdown of energy consumption (electricity and gas) by usage categories. This functionality is available both on a monthly and yearly basis via the endpoints GET usage-breakdowns/monthly and GET usage-breakdowns. Several algorithms may be used to calculate a site’s consumption disaggregation, depending on the data available for the site :

Load curve disaggregation : Based on machine learning, this algorithm is available for sites with sufficient load curve history and depends on the tenants’ country
In cases where only daily consumption data is available, a more statistical approach is used, based on the site’s consumption profile.
When only profile data is available without daily consumption data, the calculation relies on typical usage patterns of this profile type.

Data Returned

The API provides a detailed breakdown of energy consumption by usage for each category:

Percentage: The percentage of total energy consumption attributed to each usage
Energy: The estimated energy consumed for each usage (in kWh)
Cost: The estimated cost associated with each usage, based on the tariff information for the site

Usage Categories

Electricity

Heating
Sanitary Hot Water
Air Conditioning
Refrigeration
Lighting
Washing
Electric Vehicle
Cooking
Media
Swimming Pool
Always On: Devices that are always running, such as standby electronics
Other: Usages not covered by specific categories

Gas

Heating
Sanitary Hot Water
Cooking

Enhancement with connected devices consumption

The disaggregation can be enhanced with consumption data from connected devices. When a site has consumption sent by connected devices for a specific usage, the consumption disaggregation API returns this information.

Example

Here is an example request to get the electricity consumption disaggregation of September 2024 for a given site having connected heating devices: GET usage-breakdowns/monthly?begin-ts=2024-09-01T00:00:00Z&end-ts=2024-10-01T00:00:00Z&fluid=ELEC

[
    {
        "year": 2024,
        "monthlyUsageBreakdowns": [
            {
                "month": "2024-09",
                "totalCost": 93,
                "totalConsumption": 328,
                "algorithm": "DISAGGREGATION",
                "usageBreakdowns": [
                    {
                        "usage": "US_HEATING",
                        "cost": 12,
                        "percent": 13,
                        "consumption": 42,
                        "connectedPartCost": 8.61,
                        "connectedPartEnergy": 44.19
                    },
                    {
                        "usage": "US_SANITARY_HOT_WATER",
                        "cost": 27,
                        "percent": 29,
                        "consumption": 97
                    },
                    {
                        "usage": "US_AIR_CONDITIONING",
                        "cost": 0,
                        "percent": 0,
                        "consumption": 0
                    },
                    {
                        "usage": "US_WASHING_DRYING",
                        "cost": 2,
                        "percent": 2,
                        "consumption": 6,
                        "fiability": {
                            "isReliable": true,
                            "equipmentsFiability": {
                                "washerNumber": "1",
                                "dryerNumber": "1"
                            }
                        }
                    },
                    {
                        "usage": "US_FRIDGE_FREEZER",
                        "cost": 9,
                        "percent": 10,
                        "consumption": 32,
                        "fiability": {
                            "isReliable": true,
                            "equipmentsFiability": {
                                "fridgeFreezerNumber": "1"
                            }
                        }
                    },
                    {
                        "usage": "US_COOKING",
                        "cost": 4,
                        "percent": 4,
                        "consumption": 14,
                        "fiability": {
                            "isReliable": true,
                            "equipmentsFiability": {
                                "miniOvenNumber": "1",
                                "inductionPlateNumber": "1"
                            }
                        }
                    },
                    {
                        "usage": "US_LIGHTING",
                        "cost": 6,
                        "percent": 6,
                        "consumption": 21,
                        "fiability": {
                            "isReliable": true,
                            "equipmentsFiability": {
                                "lightingType": "Classique"
                            }
                        }
                    },
                    {
                        "usage": "US_ELECTRIC_VEHICLE",
                        "cost": 0,
                        "percent": 0,
                        "consumption": 0
                    },
                    {
                        "usage": "US_AUDIO",
                        "cost": 6,
                        "percent": 7,
                        "consumption": 22,
                        "fiability": {
                            "isReliable": true,
                            "equipmentsFiability": {
                                "pcNumber": "3",
                                "otherAudioEquipmentsNumber": "3",
                                "tvNumber": "1"
                            }
                        }
                    },
                    {
                        "usage": "US_ALWAYS_ON",
                        "cost": 6,
                        "percent": 7,
                        "consumption": 22
                    },
                    {
                        "usage": "US_OTHERS",
                        "cost": 21,
                        "percent": 22,
                        "consumption": 72
                    }
                ]
            }
        ]
    }
]

Tracking connected consumption by usage and by room

It is also possible to get the connected consumption of a site or a pair (site - device) on a period at a given step, broken down by usage and by room. This feature is available via the endpoints GET sites/-/connected-consumption-by-usage and GET sites/-/devices/-/connected-consumption-by-usage. To get the breakdown by room in the response, the boolean parameter withDetailsByArea should be set to true.

Example

Here is an example request to get a site’s connected consumption by usage and by room over a month:

GET sites/-/connected-consumption-by-usage?beginTs=2023-03-31T22:00:00Z&endTs=2023-04-30T22:00:00Z&stepUnit=months&withDetailsByArea=true

{
    "period": {
        "startTime": "2023-04-01T00:00:00+02:00",
        "endTime": "2023-05-01T00:00:00+02:00"
    },
    "step": "P1M",
    "units": {
        "cost": "EUR",
        "energyMeter": "KWH"
    },
    "usageConsumptions": [
        {
            "period": {
                "startTime": "2023-04-01T00:00:00+02:00",
                "endTime": "2023-05-01T00:00:00+02:00"
            },
            "byUsage": [{
            "usage": "US_HEATING",
            "energyMeter": {
                  "total": 690,
                  "byDeviceId": {
                      "device_id1": 567,
                      "device_id2": 123               
                  },
                  "byArea": [{
                    "name":"John bedroom",
                    "type": "BEDROOM",
                    "value" 567: 
                    },
                    {
                    "name":"Jane bedroom",
                    "type": "BEDROOM",
                    "value": 123
                    }
                  ]
              },
              "cost": {
                  "total": 692,
                  "byDeviceId": {
                      "device_id1": 568,
                      "device_id2": 124
                  },
                  ,
                  "byArea": [{
                    "name":"John bedroom",
                    "type": "BEDROOM",
                    "value" 568: 
                    },
                    {
                    "name":"Peter bedroom",
                    "type": "BEDROOM",
                    "value": 124
                    }
                  ]
               }
             },
          {
            "usage": "US_LIGHTING",
            "energyMeter": {
                  "total": 1530,
                  "byDeviceId": {
                      "device_id3": 543,
                      "device_id4": 987
                  },
                  "byArea": [{
                    "name":"Room 1",
                    "type": "KITCHEN",
                    "value" 1530 
                    }
                  ]
              },
              "cost": {
                  "total": 1532,
                  "byDeviceId": {
                      "device_id3": 544,
                      "device_id4": 988
                  },
                  "byArea": [{
                    "name":"Room 1",
                    "type": "KITCHEN",
                    "value" 1532 
                    }
                  ]
               }
             }
           ]
          }
      ]
  }

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

Overview

Data Returned

Usage Categories

Electricity

Gas

Enhancement with connected devices consumption

Example

Tracking connected consumption by usage and by room

Example

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

​Overview

​Data Returned

​Usage Categories

​Electricity

​Gas

​Enhancement with connected devices consumption

​Example

​Tracking connected consumption by usage and by room

​Example

Overview

Data Returned

Usage Categories

Electricity

Gas

Enhancement with connected devices consumption

Example

Tracking connected consumption by usage and by room

Example