How to report location energy usage

When you receive a LocationLPC-event, you must send a report which acknowledges the event. Later after the event has ended, you must send an energy usage report to the Energy Coordination API. These reports must be posted to the /reports endpoint. This guide details how to react and report to location-based limitation of power consumption events.

Step 1: Receive a limitation of power consumption event

First, you must have received a location-based limitation of power consumption event from the Energy Coordination API. This event will contain a unique eventId that you must use when sending the reports.

In the Sandbox-environment you may trigger test events by following the simulating events guide. We also have dedicated test areas for locations in Sandbox, which have daily automatic sendouts of events.

In the Production-environment, LPC events are generated by analysing the current grid topology and forecasting the needs in larger regions. This will change from day to day, and you should not expect that each location will receive an event every day.

Step 2: Send an acknowledgement report

When you receive the event, you must send a LocationLPCAcknowledged-report to the Energy Coordination API. This report is used operationally to ensure that you have received the event. It will also be used for analysis and debugging purposes.

Step 3: React to the event

When you receive the event, it will normally be meant for the two days after the event is sent. You will only receive events for the hours that our forecast indicates a need for change in energy usage behaviour.

Since these events are mandatory, you are required to react to all hours in the event. You are also required to report the energy usage of the location after the event has ended.

Step 4: Send the location-based energy usage report

After the event has ended, you must send an location-based energy usage report to the Energy Coordination API. This report is used in part to validate compliance with the event, and to calculate the compensation. You only have to report the hours that are in the event, and not the hours that are outside of the event.

Report guidelines Review the guidelines for sending reports on energy usage.

The report must be posted to the /reports endpoint of the Energy Coordination API.

Report formats

Reporting acknowledgement

The payload itself only contains the payloadType property, which must be set to LocationLPCAcknowledged. This payload is used operationally to ensure that you have received the event. The payload itself might in the future be extended to contain more information.

Example report

{
  "eventId": "ed7a8a7a-010f-4fad-a2e0-33dab82dccf2",
  "payloads": [
    {
      "payloadType": "LocationLPCAcknowledged"
    }
  ]
}

Reporting energy usage

The energy usage payload corresponds to a specific location that has reacted to the event. You can send multiple payloads in the same report if you have locations that have reacted to the same event.

The LocationEnergyUsage-report has the following properties:

locationId: The id of the location that the energy consumption occurred at.
meterPointId: The targeted meter point id.
points: An array of energy usage datapoints.
- kiloWattHours: The energy usage in kWh. This is the total amount of energy that the resource has consumed during the hour.
- timestamp: The timestamp of the energy usage datapoint. The timestamp must be in UTC, and correspond to the start of the hour. The timestamp must be in the format yyyy-MM-ddTHH:mm:ss.fffZ.
resolution: The resolution of the energy usage data. Currently only 01:00:00 is supported. The resolution must always match the resolution of the LPC event.
payloadType: The type of the payload. You must set this to LocationEnergyUsage in order to report the locations energy usage.

Example report

{
  "eventId": "ed7a8a7a-010f-4fad-a2e0-33dab82dccf2",
  "payloads": [
    {
      "locationId": "7751a1c1-e318-4f71-b4f4-5b6e93efb149",
      "meterPointId": "70705750009393993",
      "points": [
        {
          "kiloWattHours": 72,
          "timestamp": "2024-09-12T11:00:00+00:00"
        },
        {
          "kiloWattHours": 79,
          "timestamp": "2024-09-12T12:00:00+00:00"
        }
      ],
      "resolution": "01:00:00",
      "payloadType": "LocationEnergyUsage"
    }
  ]
}