Price curve events

When our forecast shows the need to change behaviour in a local part of the grid, the Energy Coordination API will create a PriceCurve-event to incentivize partners to either shift energy usage to more favorable hours like solar production surplus, or away from hours where the grid is strained.

How it works

The PriceCurve-event is sent to all partners which have resources that are eligible to react to the event. The event is sent for the day after the event is sent, and is relevant from midnight-to-midnight local time the next day. The event will contain a unique eventId that you must use when sending the energy usage report.

Step 1: Add your resources

To receive PriceCurve-events, you must first add your resources to the Energy Coordination API. This includes registering users and and their locations, and adding distributed energy resources to the locations if they are static. Vehicles does cannot be added to locations, but are instead added as resources directly. You can read more about this in the adding resources guide.

Step 2: Enroll eligible users

Only certain users will be eligible to participate in the price curve program. You must enroll these users to the Energy Coordination API. You will receive a list of eligible users in the UserEligibility-event. Each user that agrees to participate, and is enrolled via the API, will be able to receive price curve events. You can read more about eligibility in the user eligibility guide.

Step 3: Receive price curve events

If the Energy Coordination API has decided to incentivize a certain location and resource to shift their energy usage, it will send a PriceCurve-event to the partner that is responsible for the location and resource. This event will contain a list of targets which contains the locationId and the specific resourceId that we want to change behaviour for. The event is optional to react to.

Event format

The event is available as a JSON object with the following properties:

id: The id of the event that the report corresponds to.
createdAt: The UTC-timestamp for when the event happened
payload: The payload of the event

PriceCurve payload format

The PriceCurve-payload has the following properties:

targets: An array of targeted locations for this event. Each of the targets have the following properties:
- locationId: The id of the location that is targeted.
- resourceId: The id of the resource that is targeted.
priceCurveDelta: The price curve delta which is the delta between the current spot price curve, which is incentivized.
- points: An array of incentivized hours. Each point has the following properties:
  - price: The maximum energy usage in kWh. This is the total amount of energy that the location is allowed to consume during the hour.
  - timestamp: The start time of the max energy usage datapoint. The timestamp is in UTC, and we use the format yyyy-MM-ddTHH:mm:ss.fffZ. The length can be surmised from the resolution property. At the moment it is always an hour.
- energyUnit: The unit of the energy usage which is incentivized. This is always set to kWh.
- resolution: The resolution of the timestamps in the curve. Currently only hourly (01:00:00) is supported.
- currency: The currency of the price curve. This is the in the local currency of the price area which is incentivized for.
priceArea: The price area that the price curve is for.
payloadType: The type of the payload. For this payload it is always set to PriceCuve to identify that this is a PriceCuve event.

Example event

This is an example payload of a typical PriceCurve-event:

{
  "id": "a9bd5e1d-686e-41ff-81c3-6c1cd2601ba2",
  "createdAt": "2024-09-20T18:38:36.9991721+00:00",
  "payload": {
    "targets": [
      {
        "resourceId": "16f9f742-59fa-4063-bed2-fbd4357c4c74",
        "locationId": "fa346f1c-1d4c-4ac8-8706-06c735899cac"
      },
      {
        "resourceId": "34141283-6f33-4389-a842-1ec28b0c1269",
        "locationId": "df287fe8-2706-4fcc-a626-ec64d912c96b"
      },
      {
        "resourceId": "80a0a0df-0a5c-40c4-9e04-f13b278cacda",
        "locationId": "0c9e43fe-f9e7-48f8-9e9e-9005404d865b"
      }
    ],
    "priceCurveDelta": {
      "points": [
        {
          "price": 56.25,
          "timestamp": "2024-09-26T12:00:00+00:00"
        },
        {
          "price": 40,
          "timestamp": "2024-09-26T13:00:00+00:00"
        },
        {
          "price": 41.55,
          "timestamp": "2024-09-26T14:00:00+00:00"
        },
        {
          "price": 62.2,
          "timestamp": "2024-09-26T15:00:00+00:00"
        }
      ],
      "energyUnit": "kWh",
      "currency": "NOK",
      "resolution": "01:00:00"
    },
    "priceArea": "NO1",
    "payloadType": "PriceCurve"
  }
}

Reacting to the event

These events are optional to react to, and you do not have to send an acknowledgement that you have received the event. However, if you decide to react to the event, you must send an energy usage report to the Energy Coordination API in order to be compensated. These reports must be posted to the /reports endpoint. See the follow guide for more information:

Reporting after price curve events How to react and report to price curve events