Delivery Charge API
(Nettleie-API)

Distribution Systems Operators (DSO) - på norsk, nettselskap - provide the physical power grid from suppliers to households. They charge fees for usage which are covered in the Hark API. Read more about delivery charge here, and see status for all DSO model implementations here.

With the deliveryChargeModel query on https://api.hark.eco one can get prices, capacity levels, and other model info from a DSO.

We’ve put all the models into the same query, and split the model up into parts that have different structures reflecting the price models used by DSOs.

note

You can use the docs and schemas in the GraphQL Playground make your own queries to deliveryChargeModel, but you can also copy the complete query example found further down and modify it to fit your needs.

If you have questions, ask us on Slack, chat or send us a mail on support@harktech.no

We always try to keep up with merging of DSOs and consequently the name changes, but occasionally, we choose to keep the old names. For example, we will use the old names if two DSOs merge together, but continue using the old prices and/or GLN numbers for the different geographic areas, corresponding to the old DSOs. This is the case for the following DSOs:

• Linja: Mørenett and Linja merged to Linja, but the prices are still different and based on the old DSOs. In the API you will find them under the old DSO names.

• Noranett is the name of the merged DSO of Hålogaland kraftnett, Andøy nett and Trollfjord. Since the prices are still the same as the old DSOs, you will find them under the old DSO names.

Prerequisites

You need an API key to do deliveryChargeModel queries. Use it in our GraphQL Playground to test and explore queries, similarly to what you might have done in the Getting started guide.

If you have already been in contact with us you should have an API key with the correct permissions - if you haven't been in contact with us, feel free to send us a message on Slack, chat or send us a mail on support@harktech.no.

Model structure introduction

DSO price models have one capacityModel and one energyModel. Below is a list of all price models in use. Each of these models have a different structure describing the full price model.

• capacityModel:
  • MonthlyPeaksAtDifferentDays
  • MonthlyPeaksAtDifferentDaysLinearWithBase
  • WeightedYearlyRollingPeaksInDifferentWeeks
  • FuseAndVoltageSize
• energyModel:
  • ConstantPrice
  • DifferentPricesDayAndNight
  • DifferentPricesSeasonalDayAndNight
  • DifferentSeasonal
  • SelectableEnergyModel (made up by two or more of the above)
  • FuseBasedSelectable

A detailed and more technical description for each of these models are found in the docs and schema on GraphQL Playground (https://api.hark.eco). You will find the structure and types of both the input needed to query, and also the price models one can get in the response under Queries and deliveryChargeModel(...).

When you query for the model, you get it back as an object that includes an id, capacityModel and energyModel. Then you can check the type of energyModel and capacityModel by inspecting the field __typename.

Simple query example

A simple query to get the capacity levels from ELVERKET_HOLAND could like something like this:

query {
  deliveryChargeModel(input: { id: ELVERKET_HOLAND }) {
    id
    capacityModel {
      ... on MonthlyPeaksAtDifferentDays {
        peaksPerMonth
        capacitySteps {
          rangeInWh {
            from
            to
          }
        }
      }
    }
  }
}

Which will give you this response:

{
  "data": {
    "deliveryChargeModel": {
      "id": "ELVERKET_HOLAND",
      "capacityModel": {
        "peaksPerMonth": 3,
        "capacitySteps": [
          {
            "rangeInWh": {
              "from": 0,
              "to": 1999
            }
          },
          {
            "rangeInWh": {
              "from": 2000,
              "to": 4999
            }
          },
          {
            "rangeInWh": {
              "from": 5000,
              "to": 9999
            }
          }

          // ...
        ]
      }
    }
  }
}

And you might want to query for more than just capacity levels, so we maintain a complete query that you can use for any DSO and to get all data.

Input

When querying for a model, you can query with

• GLN (Global location number) of the DSO
• DSO’s ID, an ID we maintain as an enum of the API

The DSO's IDs can be found in the API by opening the docs in the GraphQL Playground, and search for DeliveryChargeModelId.

Complete query example

Since the API is in GraphQL, you have to specify the structure of the fields you want returned. Don’t be alarmed by the size of the query or the results. We recommend using the complete query we maintain. this will return all data for any model you query, for all supported models. (We support all models for the private market.)

note

We have published an example project on Github where we build a tool that will download prices from our API, and combine these with data downloaded from Elhub, to calculate an end user's invoice.