Core concepts

This is what the Energy Coordination API is and how it works. If you already understand what this is, go to Getting Started to learn what steps you need to go through from A to B.

Overview

The goal of the API is to create a more flexible electrical grid, solving local load balancing problems by shifting energy usage within a neighbourhood to hours that are more advantageous to the grid. The primary mechanism to achieve this is to send price incentives (see Price Curve Events) to your users. The price curve events describe hours where we want users to use energy, and how much compensation they will be awarded for their flexibility.

Reacting to price curve events is optional, but if you do, make sure to send a report back detailing how much energy was used during these hours. The compensations are provided by the electrical grid company in your area, and the user will have their bill deducted at the end of the month.

What is a user

A User represents a user or customer of your service. Use it to register Locations and Resources that your user owns. Compensations are based on location and meterpoint, and then aggregated to the user.

What is a location

A Location represents a physical location that belongs to one of your users, e.g. the user’s home, cottage or office building. We use either the location’s meterPointIds or coordinates to place the location inside a neighbourhood (electric grid area) - which in turn determines which price curve events the user will receive.

Note

The location’s coordinates is really just used as a placeholder for missing meterpoint id - enabling you to get started integrating with Spark without knowing the specific meterpoint id. Eventually you will need to supply the meterpoint ids for the location to be able to receive compensation.

Locations that only have coordinates will be able to receive and report on price signals, however the monthly accumulated compensation for that location will not be included in the final settlement until a meterpoint id is provided. If at the end of the month no meterpoint id has been provided, the compensation is lost.

What is a resource

A Resource represents a “distributed energy resource” unit that your user owns, e.g. a hot water tank, charger or vehicle. In most cases, when we talk about a resource in context of Spark, it means something that can draw power from the grid.

Utilizing the resources flexibility, we can incentives your resources to draw power when it is beneficial for the grid. In the future, we might also be able to talk about power generating resources that can supply power to the grid.

In the end, resources, together with a location, is really what is being targeted by price curve events.

In the case of a vehicle, which is not connected to a specific location/meterpoint, the location indicates where the vehicle should charge - and then the location/meterpoint will be compensated. Currently, when deciding if a vehicle should receive price curve events, we look at the user’s locations to see if any of those locations should be targeted.

What is user eligibility

User eligibility indicates whether or not the user is a potential target for Energy Coordination’s price curve events. A user becomes eligible if any of the user’s locations is within a neighbourhood where Spark wants to influence the power balance.

As a partner you can check the user’s eligibility before deciding to onboard the user into Spark.

Note

A user’s eligibility might change if there are changes to the user’s location or our analysis of the electrical grid. Subscribe to UserEligibility events to be notified of any changes.

What is user enrollment

Enrollment is a prerequisite for receiving price curve events. You can enroll your users at any time, but only users which are in eligible areas will receive price curves and compensation. Depending on how you as a partner want to communicate with your users, it might in some cases be beneficial to only prompt enrollment of users which are eligible.

What is a price curve event

A price curve event is an incentive to use energy during specific hours. If you decide to react on the event and report back to us, and the user will be compensated.

The price curve event contains priceCurveDelta and targets properties. Each point in the priceCurveDelta describes how much the user will get compensated for each energyUnit (kWh) the user uses during that hour (expressed as a negative amount relative to the spotprice). The list of targets is which specific resources are allowed to react on the price curve event.

The price curve event is sent out a day before the incentives takes effect, typically after Nordpool announces intra-day spot prices.

priceCurveEvent.json

{
    "id": "a7ef0783-5af9-44d9-bf57-b325accf01cb",
    "createdAt": "2024-05-30T13:38:24.6029874+00:00",
    "payload": {
      "targets": [
        {
          "resourceId": "e2ad3f01-d40b-46a9-8a1b-b9b3010d414b",
          "locationId": "548bb6f8-7b85-4337-9cb0-31d5df4d301a"
        }
      ],
      "priceCurveDelta": {
        "points": [
          {
            "price": -1.177455,
            "timestamp": "2024-05-31T00:00:00+00:00"
          },
          {
            "price": -0.696352,
            "timestamp": "2024-05-31T01:00:00+00:00"
          },
          {
            "price": -0.374556,
            "timestamp": "2024-05-31T02:00:00+00:00"
          }
        ],
        "energyUnit": "kWh",
        "currency": "NOK",
        "resolution": "01:00:00"
      },
      "priceArea": "NO1",
      "payloadType": "PriceCurve"
    }
}

Tip

The following conditions needs to be met in order to receive price curve events for a resource:

• The resource is able to draw energy from an eligible neighbourhood (typically this means the resource is bound to a location within such a neighbourhood)
• We want to incentive certain hours in the neighbourhood according to our analysis
• The user owning the resource is enrolled

What is an energy usage report

After you have reacted on the price curve event, you need to report the actual energy usage back to us. The report should reflect the price curve event and will be the basis for calculating the user’s compensation.

For more information on how to send a report, see reports.