> For the complete documentation index, see [llms.txt](https://docs.net2grid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.net2grid.com/net2grid-energy-ai-cloud-interface-specifications/daily-consumer-intelligence/output/disaggregation-categories.md). # Disaggregation Categories ## Disaggregation Categories The **Disaggregation Categories Report** provides a detailed breakdown of total **energy consumption per activity** for each end-user. The report answers questions such as: > “How is energy usage (electricity, gas, and production) distributed across different activities over a specific period?” Depending on configuration, the report can be generated for: * a **calendar month** (default), or * a **billing period** (optional) The report is updated dynamically and contains **cumulative values from the beginning of the reporting period up to the reporting date**. *** ### Key Characteristics * **Data-driven updates**\ The report is generated whenever new measurement data becomes available. * **Reprocessing of historical data**\ If past measurements are received, reports are recalculated for all affected dates. * **Cumulative values**\ Each report reflects total consumption from the beginning of the reporting period. * **Activity-based breakdown**\ Consumption is split into predefined categories. * **NET2GRID EnergyAI® estimation**\ Results are derived using disaggregation algorithms and improve over time. *** ### Reporting Period Configuration This configuration defines **the time range that the report covers**. It could be one of the following configurations: * Calendar Month (Default) * Billing period (Optional) #### Calendar Month (Default) * The reporting period follows the **calendar month** * Values are calculated from the **1st day of the month** * This is the default behavior #### Billing Period (Optional) If enabled: * The reporting period follows **custom billing periods** defined per installation * Billing periods may vary (e.g. monthly, bi-monthly, custom ranges) * The label partner must: * Enable billing period functionality * Provide billing period data per installation * Billing periods affect **what period is reported**, not **when the report is generated** **Fallback Behavior** If billing period mode is enabled but: * No billing periods exist for an installation, or * The reporting date does not belong to any billing period ➡️ The system automatically falls back to **calendar month reporting** *** #### Weekly Reports The **Weekly Disaggregation Categories Report**: * Covers a fixed **Monday–Sunday** period * Is **independent of billing periods** * Is **disabled by default** and available only upon request * Is generated during the first days of the following week * Is regenerated if historical data is received *** ### Report Execution Mode * Reports are generated whenever new measurement data is uploaded * If measurements are received for a past day, the system regenerates all subsequent reports affected by the update This ensures that previously generated reports are corrected using the latest available data. **Example** If data already exists up to day 15 and new data is received for day 10, the system will regenerate reports for: 10, 11, 12, 13, 14, 15 *** ### Understanding the Data #### Cumulative Consumption All values are cumulative within the reporting period. | Date | Total Consumption | | ----- | ----------------- | | 01/03 | 5 kWh | | 02/03 | 12 kWh | | 03/03 | 21 kWh | The value on 03/03 includes consumption from 01/03, 02/03, and 03/03. *** ### Installation Profile Impact Disaggregation accuracy depends heavily on the installation profile information provided by the end-user. Providing profile data improves: * detection accuracy * personalization * overall quality of results * the quality of downstream insights and recommendations However, in some cases the end-user may not complete the installation profile, may postpone doing so, or the customer may not be able to provide this information at all. #### Default Installation Profile If profile data is missing or incomplete: * a default profile is applied per label partner * missing installation demographics and appliance attributes are filled with label-partner-specific defaults * this ensures report generation can continue even without a complete end-user profile This approach reduces personalization compared to a complete installation profile. *** ## Technical Specifications ### Storage Location #### Monthly / Billing-Period Reports The disaggregation categories reports are generated under the S3 export bucket using the following format: `s3://{exportBucket}/{labelpartner}/reports/{installationIdentifier}/{serviceType}/disaggregation-categories/{filename}` **Path Parameters** * **exportBucket**: the name of the AWS S3 bucket that contains the reports * **labelpartner**: the identifier of the label partner * **installationIdentifier**: the external installation identifier provided during end-user provisioning * **serviceType**: SM **Filename Format** `{internalInstallationIdentifier}_{reportDate}_disaggregation_categories.json` Where: * **internalInstallationIdentifier**: the internal installation identifier used in NET2GRID EnergyAI® * **reportDate**: the date in `YYYYMMDD` format up to which the report was generated, i.e. the last full day for which data were available *** #### Weekly Reports Weekly disaggregation categories reports are generated under the following format: `s3://{exportBucket}/{labelpartner}/reports/{installationIdentifier}/{serviceType}/weekly-disaggregation-categories/{filename}` **Weekly Filename Format** `{internalInstallationIdentifier}_{reportWeek}_weekly_disaggregation_categories.json` Where: * **reportWeek**: the report week in `xxxxWww` ISO-8601 format *** ### Report Format The report is provided in **JSON format**. #### Main Fields | Field | Type | Monthly / Billing mode | Weekly mode | Description | | ---------------------- | ------- | ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------- | | year | integer | true | false | Optional. The year under examination. Returned only for monthly reports when billing period functionality is not enabled. | | month | integer | true | false | Optional. The month under examination. Returned only for monthly reports when billing period functionality is not enabled. | | week | string | false | true | The week under examination in `xxxxWww` ISO-8601 format. | | periodStartDate | string | true | true | Start date of the reporting period, in `YYYYMMDD` format in the installation local timezone. | | periodEndDate | string | true | true | End date of the reporting period, in `YYYYMMDD` format in the installation local timezone. | | reportingDate | string | true | true | Last date within the reporting period for which the report was generated, in `YYYYMMDD` format. | | error | string | true | true | Error code returned for the report. | | timestamp | long | true | true | UNIX timestamp in milliseconds indicating when the report was produced and published. | | version | string | true | true | Service version, e.g. `2.3`. | | electricityConsumption | object | true | true | Electricity consumption disaggregation object. | | gasConsumption | object | true | true | Gas consumption disaggregation object. | | electricityProduction | object | true | true | Electricity production disaggregation object. | | alwaysOnConsumption | object | true | true | Always-on electricity consumption disaggregation object. | | processDates | object | true | true | Contains the last date of measurements used for each commodity type. Returned only when supported by the service type (e.g. SM). | *** #### Notes * The **Monthly / Billing** column applies to both: * calendar month mode * billing period mode * The **Weekly** column applies only to weekly disaggregation reports * Fields: * `year` and `month` are **only returned when billing periods are NOT used** * `week` is **only returned in weekly reports** * All other fields are common across report types *** #### Electricity Consumption (kWh) This object contains the electricity consumption breakdown for the reporting period, expressed in **kWh**. | Field | Type | Description | | --------------- | ----- | ------------------------------------------------------------------ | | alwaysOn | float | The electricity consumption of the always-on category. | | refrigeration | float | The electricity consumption of the refrigeration category. | | spaceHeating | float | The electricity consumption of the space heating/cooling category. | | waterHeating | float | The electricity consumption of the water heating category. | | cooking | float | The electricity consumption of the cooking category. | | laundry | float | The electricity consumption of the laundry category. | | lighting | float | The electricity consumption of the lighting category. | | entertainment | float | The electricity consumption of the entertainment category. | | electricVehicle | float | The electricity consumption of the electric vehicle category. | | poolOrSauna | float | The electricity consumption of the pool/sauna category. | | other | float | The electricity consumption of the other category. | | total | float | The total electricity consumption in kWh. | *** #### Gas Consumption This object contains the gas consumption breakdown for the reporting period, expressed in the **input unit of the gas measurements**. | Field | Type | Description | | ------------ | ----- | --------------------------------------------------------------------- | | spaceHeating | float | The gas consumption of the space heating/cooling category. | | waterHeating | float | The gas consumption of the water heating category. | | cooking | float | The gas consumption of the cooking category. | | total | float | The total gas consumption in the unit in which gas data are measured. | *** #### Electricity Production This object contains the electricity production breakdown for the reporting period, expressed in **kWh**. | Field | Type | Description | | ----- | ----- | ------------------------------------------------- | | solar | float | The electricity production of the solar category. | | total | float | The total electricity production in kWh. | *** #### Always-On Consumption This object contains the breakdown of **always-on electricity consumption** for the reporting period, expressed in **kWh**. | Field | Type | Description | | ----------------------- | ----- | -------------------------------------------------------------------------------- | | whitegoods | float | The always-on electricity consumption of the whitegoods category. | | cooking | float | The always-on electricity consumption of the cooking category. | | spaceHeatingAndCooling | float | The always-on electricity consumption of the space heating and cooling category. | | computersAndPeripherals | float | The always-on electricity consumption of the computers and peripherals category. | | homeEntertainment | float | The always-on electricity consumption of the home entertainment category. | | other | float | The always-on electricity consumption of the other category. | | total | float | The total always-on electricity consumption in kWh. | *** #### Process Dates The `processDates.lastProcessCommodityDate` object indicates, per metric, the **last day of data that was taken into account during report generation**. | Field | Type | Description | | ----- | ------ | ----------------------------------------------------------------------------------------------- | | csd | string | Optional. The last date that electricity consumption data were available, in `YYYYMMDD` format. | | csr | string | Optional. The last date that return-to-grid data were available, in `YYYYMMDD` format. | | gas | string | Optional. The last date that gas consumption data were available, in `YYYYMMDD` format. | *** #### Error Codes The following error codes may be returned in Disaggregation Categories Reports. | Code | Message | Monthly / Billing Applicable | Weekly Applicable | Disaggregation Provided | Description | | ----- | ------------------------------------------------------- | ---------------------------- | ----------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | null | - | true | true | true | No error occurred during report generation. | | 30001 | Incomplete Profile for Disaggregation Categories Report | true | true | true | Essential installation profile fields are missing or not filled correctly. | | 30002 | Erroneous Profile Info | true | true | false | One or more profile values are excessive, inconsistent, or unrealistic. | | 30003 | No Current Period Disaggregation Document Available | true | true | false | No measurements are available for the installation for the requested reporting period. | | 30004 | Excessive Value on Disaggregation Document | true | true | false | The total energy consumption value for the requested reporting period is abnormally high and considered invalid. | | 30005 | Negative Value on Disaggregation Document | true | true | false | The total energy consumption value for the requested reporting period is negative. | | 30008 | No billing period detected | true | false | true | Billing period functionality is enabled, but the reporting date does not belong to any billing period. In this case, the system falls back to monthly reporting. | | 30010 | Missing Secondary Meter Measurements | true | true | true | Secondary meter functionality is enabled and expected, but measurements are missing for at least one secondary-meter appliance. | **Notes** * **Monthly / Billing Applicable** indicates whether the error code may appear in monthly or billing-period reports. * **Weekly Applicable** indicates whether the error code may appear in weekly reports. * **Disaggregation Provided** indicates whether the report still contains disaggregation results. * `true` means the report is still produced and includes disaggregation output. * `false` means the report does not contain disaggregation results. *** ### Example Report Files #### Monthly / Billing-Period A disaggregation categories report may be generated in a location such as: `s3://s3-export-ABC/labelpartnerB/reports/installationX/SM/disaggregation-categories/abc123456_20230105_disaggregation_categories.json` Example contents: ```json { "year": 2023, "month": 1, "error": "null", "timestamp": 1673109098233, "periodStartDate": "20230101", "periodEndDate": "20230131", "reportingDate": "20230105", "version": "2.3", "electricityConsumption": { "alwaysOn": 1.75783, "refrigeration": 1.40626, "spaceHeating": 0.0, "waterHeating": 0.0, "cooking": 0.52733, "laundry": 1.14259, "lighting": 0.70313, "entertainment": 0.96679, "electricVehicle": 0.0, "poolOrSauna": 0.0, "other": 0.79101, "total": 7.295 }, "gasConsumption": { "spaceHeating": 2.90705, "waterHeating": 0.24593, "cooking": 0.0, "total": 3.153 }, "electricityProduction": { "solar": 0.87199, "total": 0.87199 }, "alwaysOnConsumption": { "whitegoods": 0.10018, "cooking": 0.11249, "spaceHeatingAndCooling": 0.04921, "computersAndPeripherals": 0.69257, "homeEntertainment": 0.71016, "other": 0.09316, "total": 1.75783 }, "processDates": { "lastProcessCommodityDate": { "csd": "20230105", "csr": "20230105", "gas": "20230105" } } } ``` *** #### Weekly Report A weekly disaggregation categories report may be generated in a location such as: `s3://s3-export-ABC/labelpartnerB/reports/installationX/SM/weekly-disaggregation-categories/abc123456_2023W32_weekly_disaggregation_categories.json` Example contents: ```json { "week": "2023W32", "error": "null", "timestamp": 1673109098233, "periodStartDate": "20230807", "periodEndDate": "20230813", "reportingDate": "20230813", "version": "2.3", "electricityConsumption": { "alwaysOn": 1.75783, "refrigeration": 1.40626, "spaceHeating": 0.0, "waterHeating": 0.0, "cooking": 0.52733, "laundry": 1.14259, "lighting": 0.70313, "entertainment": 0.96679, "electricVehicle": 0.0, "poolOrSauna": 0.0, "other": 0.79101, "total": 7.295 }, "gasConsumption": { "spaceHeating": 2.90705, "waterHeating": 0.24593, "cooking": 0.0, "total": 3.153 }, "electricityProduction": { "solar": 0.87199, "total": 0.87199 }, "alwaysOnConsumption": { "whitegoods": 0.10018, "cooking": 0.11249, "spaceHeatingAndCooling": 0.04921, "computersAndPeripherals": 0.69257, "homeEntertainment": 0.71016, "other": 0.09316, "total": 1.75783 }, "processDates": { "lastProcessCommodityDate": { "csd": "20230105", "csr": "20230105", "gas": "20230105" } } } ``` *** ### Notification Mechanism #### Monthly / Billing-Period Reports The queue used to publish messages when a disaggregation categories report is generated will be communicated separately to the customer by NET2GRID. Usually, the queue name is: `disaggregation_categories_{labelpartner}` The published message contains the following fields: | Field | Type | Description | | -------- | ------ | ------------------------------------------------ | | bucket | string | The name of the bucket that contains the report. | | filename | string | The full path of the generated file. | Example message: ```json { "bucket": "s3-export-customerA", "filename": "/labelpartnerB/reports/installationX/SM/disaggregation-categories/abc123456_20230105_disaggregation_categories.json" } ``` Each message also contains an attribute named `routingKey` of type `String` with value: `{installationIdentifier}.disaggregation_categories` *** #### Weekly Reports The queue used to publish messages when a weekly disaggregation categories report is generated will be communicated separately to the customer by NET2GRID. Usually, the queue name is: `weekly_disaggregation_categories_{labelpartner}` The published message contains the following fields: | Field | Type | Description | | -------- | ------ | ------------------------------------------------ | | bucket | string | The name of the bucket that contains the report. | | filename | string | The full path of the generated file. | Example message: ```json { "bucket": "s3-export-customerA", "filename": "/labelpartnerB/reports/installationX/SM/weekly-disaggregation-categories/abc123456_20230105_weekly_disaggregation_categories.json" } ``` Each message also contains an attribute named `routingKey` of type `String` with value: `{installationIdentifier}.weekly_disaggregation_categories` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.net2grid.com/net2grid-energy-ai-cloud-interface-specifications/daily-consumer-intelligence/output/disaggregation-categories.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.