> 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-grid-intelligence/input/measurements.md). # Measurements ## Measurements This document describes the measurement input specifications required for the Monthly Grid Intelligence tier. DER Detection uses measurement data to identify Distributed Energy Resources such as: * Photovoltaics / Solar Panels * Battery Energy Storage Systems (BESS) * Electric Vehicles * HVAC systems *** ### Supported Metrics DER Detection supports the following mains meter metrics: | Metric | Description | Required | | ------ | --------------------------------------- | -------- | | `CSD` | Electricity consumption measurements | Yes | | `CSR` | Electricity return-to-grid measurements | Optional | #### Important Notes * `CSD` is required. * `CSR` is required when energy is produced or injected back to the grid. * `CSR` may be omitted if no energy is produced in the household. *** ### Supported Granularity The following granularities are supported: * 15 minutes * 60 minutes *** ### Measurement Semantics The uploaded measurements represent: * timestamped delta energy values * expressed per interval Measurement values are expected to represent the consumed or produced energy during the interval starting from the provided timestamp until the next interval timestamp. *** ### Supported Units By default, measurement values are expected in: ``` Wh ``` Support for `kWh` can optionally be enabled through label-partner-specific configuration. *** ### Timezone Requirements Measurements are expected to correspond to the installation local timezone. The timestamps inside the file are expected to be UNIX timestamps in milliseconds, expressed in UTC. *** ## Data Exchange Measurement files are exchanged through AWS S3. DER input files must be uploaded under the `der-measurements` folder. Once uploaded, DER Detection may be triggered, depending on the execution rules. *** ### File Format Measurement files must: * use CSV format * use UTF-8 encoding without BOM * use comma (`,`) as separator * use dot (`.`) as decimal separator A header row is allowed but not required. *** ### CSV Structure Each row contains: | Field | Description | | --------- | ------------------------------------ | | Timestamp | UNIX timestamp in milliseconds (UTC) | | Value | Delta energy value | *** ### Example ```csv Timestamp,Value 1714521600000,245 1714522500000,301 1714523400000,276 ``` *** ## Directory Structure ### Path Format ``` s3://{bucket_name}/{labelpartner}/der-measurements/{external-installation-id}/{external-meter-id}/ ``` ### Filename Format ``` {external-installation-id}_{start-date}_{stop-date}_{metric}.csv ``` *** ### Path and Filename Parameters | Parameter | Description | | -------------------------- | --------------------------------------------------------------------------- | | `bucket_name` | The AWS S3 bucket agreed between CUSTOMER and NET2GRID. | | `labelpartner` | The label partner identifier provided by NET2GRID during onboarding. | | `external-installation-id` | Unique identifier of the installation/household. | | `external-meter-id` | Unique identifier of the meter providing the measurements. | | `start-date` | Start date of the measurements contained in the file, in `YYYYMMDD` format. | | `stop-date` | End date of the measurements contained in the file, in `YYYYMMDD` format. | | `metric` | Metric identifier. Supported values: `CSD`, `CSR`. | *** ## DER Measurements Processing ### File Rules Each uploaded DER measurement file: * must correspond to a single installation * must correspond to a single metric * may contain measurements covering multiple days * may contain long continuous periods of measurements * must not contain measurements from multiple installations A separate file is expected for: * each installation * each metric *** ### DER Detection Execution Logic Uploading DER measurements does not always trigger a DER Detection execution. A DER Detection execution is triggered only when all the following conditions are met: * new measurement data has been uploaded * the installation has sufficient measurement history * at least one month has elapsed since the installation’s last successful DER Detection execution *** #### Measurement History Requirement DER Detection requires measurement data to be available for more than 3 months. Ideally, one full year of measurement data should be available, as this improves the quality of the detection. *** #### Execution Frequency Rule DER Detection is controlled by a one-month execution gate. * If new measurements are uploaded and at least one month has elapsed since the last successful DER Detection execution, a new execution may be triggered. * If new measurements are uploaded before one full month has elapsed, no new DER Detection execution is performed. * Once one full month has elapsed, the next upload of DER measurements triggers a new DER Detection execution. * No execution is performed if no new measurement data is uploaded, even if the one-month period has elapsed. *** #### Reporting Period The DER Detection analysis period depends on the amount of available measurement data: * If a full year of measurement data is available, DER Detection uses the full year. * If less than one year is available, DER Detection uses the entire available measurement period. *** ### Measurement Quality Expectations The uploaded DER measurements are expected to: * contain valid timestamps * contain positive values * follow the expected granularity consistently * contain sufficiently complete data Poor-quality measurements may lead to: * reduced detection accuracy * missing DER Detection reports *** ### Measurements Overwrite Behavior NET2GRID EnergyAI® imports measurements using a last-write-wins approach. If multiple uploaded files contain measurements for the same installation, metric, and timestamps: * the latest uploaded measurements overwrite previously imported values This mechanism allows: * correction of previously uploaded measurements * re-upload of improved-quality data * backfilling of historical periods *** ### Permissions NET2GRID creates the S3 bucket and grants the customer permissions to: * list objects * upload objects * retrieve objects * delete objects NET2GRID also securely shares the required IAM credentials during onboarding. --- # 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-grid-intelligence/input/measurements.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.