Reporting energy usage

After your energy resource, like EV or hot-water tank, has reacted to a price curve event, you must send an energy usage report to the Energy Coordination API. This report is used to calculate the compensation for your end-customers.

Step 1: Receive a price curve event

First, you must have received a price curve event from the Energy Coordination API. This event will contain a unique eventId that you must use when sending the energy usage report.

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

In the Production-environment, price curve events are generated by analysing the current grid topology and forecasting the needs in local areas. This will change from day to day, and you should not expect that each resource will receive an event every day.

Step 2: Process the event for next-day consumption

When you receive a price curve event, it will be for the day after the event is sent. All events are relevant from midnight-to-midnight local time the next day, but you will only receive for the hours that our forecast indicates a need for change in energy usage behaviour.

This means that you will receive an event on Monday for consumption on Tuesday. You should process the event and prepare the resources to react to the event on Tuesday in the hours that are indicated. You are not required to react to all hours in the event, only the hours that you can. You are also free to ignore the event if you do not have the capacity to react.

Step 3: Send the energy usage report

After the event has ended, you must send an energy usage report to the Energy Coordination API. This report is used to calculate the compensation for your end-customers. You only have to report the hours that you have reacted to.

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 format

The report is sent as a JSON object with the following properties:

• eventId: The id of the event that the report corresponds to.
• payloads: An array of report payloads.

A report always in reaction to a specific event, and can contain multiple payloads. In the future we will support more report payload types, but for now the only supported payload type is EnergyUsageReportPayload.

EnergyUsageReportPayload format

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

The EnergyUsageReportPayload has the following properties:

• resourceId: The id of the resource that has consumed energy.
• locationId: The id of the location that the energy consumption occurred at.
• meterPointId (optional): The meter point id of the meter the resource has consumed energy through. This property is intended to be used for electric vehicles, if there are multiple meters at the same location, and you want to specify which meter the energy consumption occurred through. This will affect which meter is compensated.
• curvePoints: 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 price curve event.
• payloadType: The type of the payload. You must set this to EnergyUsage in order to report energy usage. More payload types will be supported in the future.

Important!

The curvePoints array contains the energy usage data for the resource and location. It is very important that these have the same timestamps as the price curve event, and that the timestamps are in UTC. At the moment each price curve point is 1 hour long, and the timestamp should be the start of the hour.

Example

The following is a JSON-object example of an energy usage report payload:

payload-example.json

{
  "eventId": "4d552526-25c1-42e6-8c4b-7c1f1dc666a4",
  "payloads": [
    {
      "resourceId": "ccbde8e6-39c0-4234-b7aa-03488e507cf6",
      "locationId": "47aad69f-0fb4-479a-aa73-45b5beab7340",
      "meterPointId": null,
      "curvePoints": [
        {
          "kiloWattHours": 3.14,
          "timestamp": "2024-05-16T11:00:00.000+00:00"
        },
        {
          "kiloWattHours": 2.71,
          "timestamp": "2024-05-16T12:00:00.000+00:00"
        }
      ],
      "resolution": "01:00:00",
      "payloadType": "EnergyUsage"
    }
  ]
}