> 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/appliance-events.md). # Appliance Events ## Appliance Events The **Appliance Events Report** provides a detailed view of **detected appliance usage events** for a specific day. The report answers questions such as: > “When did a specific appliance operate during the day and how much energy did it consume?” The report is generated whenever new measurement data is uploaded. *** ### Key Characteristics * **Daily event detection**\ The report captures appliance usage events for each day. * **Event-based analysis**\ Each detected appliance usage is represented as an event with: * start time * end time * energy consumption * **Focus on high-impact appliances**\ Detection focuses on appliances with significant contribution to total consumption. * **NET2GRID EnergyAI® estimation**\ Events are derived using disaggregation algorithms and improve over time. *** ### Supported Appliances Currently, the Appliance Events Report supports only: | Appliance Identifier | Description | | -------------------- | ---------------- | | electricVehicle | Electric Vehicle | > The report is generated only for installations where an Electric Vehicle has been detected. *** ### Understanding the Data Each event represents a detected charging session of the Electric Vehicle. * Multiple events may exist within the same day * Each event corresponds to a distinct charging activity * The sum of all events represents the total EV consumption for that day *** ### Report Generation Logic * The report is generated whenever new measurement data is uploaded * If measurements are received for a past day, the system regenerates the report for that specific day This ensures that the report always reflects the latest available data. *** ### Requirements The Appliance Events Report is generated only if: * The feature is **enabled at label partner level** * The installation has a **detected Electric Vehicle** * Measurement data is available for the reporting day *** ## Technical Specifications ### Storage Location The Appliance Events reports are generated under the S3 export bucket using the following format: `s3://{exportBucket}/{labelpartner}/reports/{installationIdentifier}/{serviceType}/appliance-events/{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 provisioning * **serviceType**: SM (low-resolution measurement data) #### Filename Format `{internalInstallationIdentifier}_{reportDate}_appliance_events.json` Where: * **internalInstallationIdentifier**: the internal installation identifier used in NET2GRID EnergyAI® * **reportDate**: the date in `YYYYMMDD` format for which the report was generated *** ### Report Format The report is provided in **JSON format**. #### Main Fields | Field | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------ | | date | string | The reporting date in `YYYYMMDD` format. | | error | string | Error code returned for the report. | | timestamp | long | UNIX timestamp (milliseconds) indicating when the report was produced. | | version | string | Service version, e.g. `4.6`. | | sunriseTimestamp | long | Sunrise time for the installation location, as UNIX timestamp (seconds). | | sunsetTimestamp | long | Sunset time for the installation location, as UNIX timestamp (seconds). | | reportEvents | list | List of detected appliance events. | *** #### ReportEvents Object Each detected appliance event contains: | Field | Type | Description | | ------------- | ------- | ----------------------------------------------------------------------- | | id | integer | Unique identifier of the event (per installation). | | applianceType | string | Appliance type (currently `electricVehicle`). | | startTime | long | Start timestamp of the event (UNIX seconds). | | stopTime | long | End timestamp of the event (UNIX seconds). | | usage | float | Energy consumption of the event, in kWh for the specific time interval. | *** #### Error Codes | Code | Message | Events Provided | Description | | ----- | ------------------------------------ | --------------- | --------------------------------------------------------------- | | null | - | true | No error occurred during report generation. | | 20003 | No Events Available | false | No Electric Vehicle events were detected for the reporting day. | | 30006 | Null or Empty Measurements | false | No measurements available for the reporting day. | | 30007 | Insufficient Data Measurements | false | Measurements are insufficient for disaggregation analysis. | | 30010 | Missing Secondary Meter Measurements | true | Secondary meter measurements are missing while expected. | *** ### Example Report File A report may be generated in a location such as: `s3://s3-export-ABC/labelpartnerB/reports/installationX/SM/appliance-events/abc123456_20230523_appliance_events.json` Example contents: ```json { "date": "20230523", "error": "null", "timestamp": 1684895713243, "version": "4.6", "sunriseTimestamp": 1684813380, "sunsetTimestamp": 1684870560, "reportEvents": [ { "applianceType": "electricVehicle", "startTime": 1684840875, "stopTime": 1684844133, "usage": 0.885, "id": 5293 } ] } ``` *** ### Notification Mechanism A message is published when a report is generated. Queue: `appliance_events_{labelpartner}` #### Message Format ```json { "bucket": "s3-export-customerA", "filename": "/labelpartnerB/reports/installationX/SM/appliance-events/abc123456_20230523_appliance_events.json" } ``` Routing key: `{installationIdentifier}.appliance_events` --- # 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/appliance-events.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.