Reporting energy usage

After receiving and acting on an event such as PriceCurve and LPC, you must send an energy usage report to the Energy Coordination API. This report is used to calculate the compensation for your end-customers.

Report on an event

The event will contain a unique eventId that you must use when sending the energy usage report.

When you decide to act on an event, we want you to report back using the same hours and resolution as in the event. You only have to report the hours that you have reacted to, but you may also report on hours not in the event, these hours will simply be ignored.

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 is always in reaction to a specific event, and can contain multiple payloads. For energy usage reports, the payload type is EnergyUsage.

EnergyUsage payload 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 EnergyUsage-payload 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.

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 original event, and that the timestamps are in UTC. At the moment each point is 1 hour long, and the timestamp should be the start of the hour.

Example report

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

energy-usage-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"
    }
  ]
}