> 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/monthly-home-energy-reports/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 month?” The report is generated on a **monthly basis** and contains the total disaggregated consumption values for the full calendar month under examination. *** ### Key Characteristics * **Monthly execution**\ Reports are generated once per month, typically during the first days of the following month. * **Calendar-month reporting**\ The reporting period always follows the calendar month. * **Historical/Delayed reprocessing support**\ If historical or delayed measurements are received for a previously processed month, the corresponding report is regenerated. * **Cumulative values**\ Each report reflects total consumption for the entire reporting month. * **Activity-based breakdown**\ Consumption is split into predefined categories. * **NET2GRID EnergyAI® estimation**\ Results are derived using disaggregation algorithms and improve over time. *** ### Reporting Period The reporting period always follows the calendar month. * Values are calculated from the first day of the month * Reports contain cumulative values for the entire month * Reports are generated after the month has completed *** ### Report Generation Logic #### Monthly Execution * Measurements are processed continuously as they are uploaded * The Disaggregation Categories Report is generated once per month * Report generation usually occurs during the first days of the following month *** #### Historical / Delayed Measurement Reprocessing If corrected, delayed, or backfilled measurements are received for a month that has already been processed: * the corresponding monthly report is regenerated * the updated report replaces the previous version This ensures that the report always reflects the latest available measurements. *** ### 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 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 last day of the reporting month in `YYYYMMDD` format *** ### Report Format The report is provided in **JSON format**. #### Main Fields | Field | Type | Description | | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | year | integer | The year under examination. | | month | integer | The month under examination. | | periodStartDate | string | Start date of the reporting period, in `YYYYMMDD` format in the installation local timezone. | | periodEndDate | string | End date of the reporting period, in `YYYYMMDD` format in the installation local timezone. | | reportingDate | string | Last date within the reporting period for which the report was generated, in `YYYYMMDD` format. | | error | string | Error code returned for the report. | | timestamp | long | UNIX timestamp in milliseconds indicating when the report was produced and published. | | version | string | Service version, e.g. `2.3`. | | electricityConsumption | object | Electricity consumption disaggregation object. | | gasConsumption | object | Gas consumption disaggregation object. | | electricityProduction | object | Electricity production disaggregation object. | | alwaysOnConsumption | object | Always-on electricity consumption disaggregation object. | | processDates | object | Contains the last date of measurements used for each commodity type. Returned only when supported by the service type (e.g. SM). | *** #### 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 | Disaggregation Provided | Description | | ----- | ------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | null | - | true | No error occurred during report generation. | | 30001 | Incomplete Profile for Disaggregation Categories Report | true | Essential installation profile fields are missing or not filled correctly. | | 30002 | Erroneous Profile Info | false | One or more profile values are excessive, inconsistent, or unrealistic. | | 30003 | No Current Period Disaggregation Document Available | false | No measurements are available for the installation for the requested reporting period. | | 30004 | Excessive Value on Disaggregation Document | false | The total energy consumption value for the requested reporting period is abnormally high and considered invalid. | | 30005 | Negative Value on Disaggregation Document | false | The total energy consumption value for the requested reporting period is negative. | | 30010 | Missing Secondary Meter Measurements | true | Secondary meter functionality is enabled and expected, but measurements are missing for at least one secondary-meter appliance. | * **Disaggregation Provided** indicates whether the report still contains disaggregation results. * `true` means the report includes disaggregation output. * `false` means the report does not contain disaggregation results. *** ### Example Report Files A disaggregation categories report may be generated in a location such as: `s3://s3-export-ABC/labelpartnerB/reports/installationX/SM/disaggregation-categories/abc123456_20230131_disaggregation_categories.json` Example contents: ```json { "year": 2023, "month": 1, "error": "null", "timestamp": 1673109098233, "periodStartDate": "20230101", "periodEndDate": "20230131", "reportingDate": "20230131", "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": "20230131", "csr": "20230131", "gas": "20230131" } } } ``` *** ### Notification Mechanism The queue used to publish messages when a disaggregation categories report is generated will be communicated separately to the customer by NET2GRID. The queue name typically follows the format: `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_20230131_disaggregation_categories.json" } ``` Each message also contains an attribute named `routingKey` of type `String` with value: `{installationIdentifier}.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/monthly-home-energy-reports/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.