> 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/insights.md). # Insights ## Insights The **Insights Report** provides a comparative overview of an installation’s overall and disaggregation-category-level energy consumption. The report answers questions such as: > “How does this installation’s consumption compare with its own past behavior and with other similar installations?” Insights are generated by comparing the installation against: * its **own historical consumption** from the previous period (**self comparison**), and * the consumption of **similar installations** with comparable profile characteristics (**peer comparison**) Comparisons may be applied to: * total electricity delivered from the grid * total electricity returned to the grid * gas consumption * electricity categories These insights are intended to help end-users better understand their energy behavior and identify opportunities for reduction or improvement. *** ### Key Characteristics * **Comparative insights**\ The report compares current-period consumption against both historical and peer benchmarks. * **Self and peer comparison**\ Insights may describe how the installation performs relative to: * its previous month * similar installations in the same peer group * **Multi-domain coverage**\ Comparisons may apply to electricity, gas and disaggregation categories. * **NET2GRID EnergyAI® estimation**\ Insights are derived from disaggregation results and profile-based clustering. *** ### Understanding the Data Each insight represents a comparison between the installation’s current usage and a benchmark value. The report may contain: * **Self insights**\ Comparing the current period with the installation’s own previous period * **Peer insights**\ Comparing the current period with the median usage of similar installations Each insight contains: * the actual usage for the current period * the benchmark value * the difference in kWh * the difference in percentage * a status indicating the severity of the deviation * a relevance score indicating how important the insight is for the installation *** ### Report Generation Logic * The monthly insights report is generated once per month * It covers the **previous calendar month** * It is generated only if new measurement data became available for the installation during that month *** ### Requirements The Insights Report is generated only if measurement data is available for the reporting period. *** ### Installation Profile Impact #### Peer Comparison For peer comparison to be available, the following minimum profile information is required: * Country * Postal Code * Number of Occupants * Property Type * Property Age If this information is missing, peer insights may not be available. *** ## Technical Specifications ### Storage Location The monthly insights reports are generated under the S3 export bucket using the following format: `s3://{exportBucket}/{labelpartner}/reports/{installationIdentifier}/{serviceType}/insights/{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}_{reportMonth}_insights.json` Where: * **internalInstallationIdentifier**: the internal installation identifier used in NET2GRID EnergyAI® * **reportMonth**: the reporting month in `YYYYMM` 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. | | error | string | Error code returned for the report. | | timestamp | long | UNIX timestamp in milliseconds indicating when the report was produced and published. | | serviceType | string | `SM` | | version | string | Service version, e.g. `2.3`. | | clusterId | string | Unique identifier of the peer comparison cluster to which the installation belongs. | | insights | list | List of calculated `InsightReportObjects` for the installation and reporting period. | *** #### InsightReportObjects Each insight object contains: | Field | Type | Description | | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Insight identifier in the format `aa-t-pp`, where: `aa` is the disaggregation category code, `t` is the timeOfUse code (Currently only `T` is supported), and `pp` is the comparison type code | | appliance | string | Disaggregation Category or `total`, depending on the insight. | | type | string | Insight type: `self` or `peer`. | | timeOfUse | string | Time-of-use dimension of the insight. Currently: `total`. | | data | list | List of `InsightData` objects. | | status | string | Status level of the insight, from `0` (Very low) to `6` (Very high). | | relevance | float | Relevance score of the insight for the installation. Higher values indicate higher importance. | | isPositive | boolean | Indicates whether the insight reflects a positive relevance (bad practice) or a negative relevance (good practice). | *** **Disaggregation Categories Codes** | Code | Description | | ---- | --------------------------- | | TE | Total Electricity Delivered | | AON | Always On | | RFR | Refrigeration | | LIG | Lighting | | ENT | Entertainment | | LAU | Laundry | | COO | Cooking | | EV | Electric Vehicle | | WH | Water Heating | | SH | Space Heating | | OTH | Other | | TG | Total Gas Delivered | | COOG | Cooking using Gas | | SHG | Space Heating using Gas | | WHG | Water Heating using Gas | **Comparison Type Codes (`pp`)** | Code | Description | | ---- | --------------- | | PP | Self comparison | | Ot | Peer comparison | *** #### InsightData Object Each `InsightData` object contains one metric used in the comparison. | Field | Type | Description | | ----- | ------ | ----------------------------------------------------------------------------- | | name | string | Metric name. Supported values: `benchmark`, `usage`, `deltaKwh`, `deltaPerc`. | | value | float | Metric value. | **Supported InsightData Metrics** | Name | Description | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | benchmark | Benchmark value used for the comparison. For self insights, this is the previous period’s consumption. For peer insights, this is the peer group median. | | usage | Actual energy consumption value for the current reporting period. | | deltaKwh | Absolute difference between usage and benchmark (`usage - benchmark`). | | deltaPerc | Relative difference between usage and benchmark (`deltaKwh / benchmark`). | *** #### Error Codes | Code | Message | Insights Provided | Description | | ----- | --------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | null | - | true | No error occurred during report generation. | | 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. | | 40001 | Incomplete Profile for Insights Reports | false | Essential profile information required for insights is missing or invalid. | | 40002 | No Peer Installations Available for Comparison | true | No peer installations are available in the same comparison group. Self comparison only is provided. | | 40003 | No Previous Period Consumption Available for Comparison | true | No previous period consumption is available for self comparison. Peer comparison only is provided. | | 40004 | No Peer Installations and Previous Period's Measurements Available for Comparison | false | Neither peer comparison nor self comparison can be generated. | * **Insights Provided** indicates whether the report still contains insight results. *** ### Example Report Files A monthly insights report may be generated in a location such as: `s3://s3-export-ABC/labelpartnerB/reports/installationX/SM/insights/abc123456_202304_insights.json` Example data: ```json { "year": 2023, "month": 4, "error": "null", "timestamp": 1683068106236, "serviceType": "SM", "version": "3.12", "clusterId": "country_BE_postalCodeRange_0_3990_5Occupant(s)_post-2000_end-terrace", "insights": [ { "id": "EV-T-Ot", "appliance": "electricVehicle", "type": "peer", "timeOfUse": "total", "data": [ { "name": "usage", "value": 0.0 }, { "name": "benchmark", "value": 62.981 }, { "name": "deltaKwh", "value": -62.981 }, { "name": "deltaPerc", "value": -100.0 } ], "status": "0", "relevance": 1.0, "isPositive": false }, { "id": "WHG-T-PP", "appliance": "waterHeating", "type": "self", "timeOfUse": "total", "data": [ { "name": "usage", "value": 43.218 }, { "name": "benchmark", "value": 21.533 }, { "name": "deltaKwh", "value": 21.684 }, { "name": "deltaPerc", "value": 100.703 } ], "status": "6", "relevance": 1.0, "isPositive": true }, { "id": "SHG-T-PP", "appliance": "spaceHeating", "type": "self", "timeOfUse": "total", "data": [ { "name": "usage", "value": 65.525 }, { "name": "benchmark", "value": 154.652 }, { "name": "deltaKwh", "value": -89.127 }, { "name": "deltaPerc", "value": -57.63 } ], "status": "0", "relevance": 1.0, "isPositive": false } ] } ``` *** ### Notification Mechanism A message is published when a monthly insights report is generated. Queue: `insights_{labelpartner}` #### Message Format ```json { "bucket": "s3-export-customerA", "filename": "/labelpartnerB/reports/installationX/SM/insights/abc123456_202304_insights.json" } ``` Routing key: `{installationIdentifier}.insights` --- # 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/insights.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.