> ## Documentation Index > Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 ` ```json theme={null} [ { "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` ```json theme={null} { "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 } ] } } ] } ] } ```