The Nationaal Energie Dashboard API provides insight into the current, forecasted and historical sustainable energy generation and consumption in the Netherlands.
What is an API?
An API (Application Programming Interface) is a software interface through which two applications can easily communicate with each other. By submitting a request with certain parameters such as the sustainable source and date, the NetAnders API returns the requested energy data.
What can you do with the API?
If you have the right authorisation, with the API you gain insight into:
Near-realtime electricity generation and gas consumption in the Netherlands. The total and broken down by energy carrier.
Week ahead forecast of solar energy, onshore wind energy, offshore wind energy, gas consumption of households and small businesses. For solar energy and onshore wind energy there is also a breakdown by provinces; for offshore wind energy there is a breakdown by individual offshore wind farms.
The production in capacity (kW) and in volume (kWh)
The utilization rates of energy sources expressed in percentages compared to the installed capacity
The various energy sources. Get insight to all of them of just a selection.
The historical sustainable production from 2016, the non-sustainable electricity production from 2021
10 minutes, 15 minutes, hour, day, month and year values
….
What type of API is it?
The Nationaal Energie Dashboard API is a RESTful Open Api. The following file formats are available: jsonld, jsonhal, jsonapi, json, xml, csv and html.
Access to the API - API Key
You can make an account on ned.nl. In your account you can generate an API Key. This unique key gives access to requesting energy data from the Nationaal Energie Dashboard API. The API key must be sent with every request. Do not give the key to others.
API specifications
For the developers, the detailed specifications of the API can be found in Swagger UI or Redoc via the following links:
• Swagger UI: https://api.netanders.io/v1
• Redoc: https://api.netanders.io/v1?ui=re_doc
API request limit
The current rate limit of the API is set at 400 requests per minute.
Submitting a request
When submitting a request, a number of parameters must be included. The table below shows and describes the available parameter values. You can enter an individual value or a collection of values that refer to a series of individual values.
Example for a request
Suppose you want to receive the Dutch solar data in 10 minutes values on November 16, 2020 in json. To do this, include the following parameters in the request. Below we also highlight a request in cURL, PHP-cURL and Python.
The header
Accept: application/ld+json: json – file format. X-AUTH-TOKEN: YourSuperSecretApiKey – API Key
Main message
Point: 0 - Netherlands Type: 2 - Solar Granularity 3 - 10 min Timezone 1 - UTC Classification 2 – current Activity 1 - providing Validfromstrictlybefore 2020-11-16 Validfromafter 2020-11-17
cURL
curl --location -g --request GET 'https://api.netanders.io/v1/utilizations?point=0&type=2&granularity=3&granularitytimezone=1&classification=2&activity=10&validfrom[strictly_before]=2020-11-17&validfrom[after]=2020-11-16' \ --header 'X-AUTH-TOKEN: YourSuperSecretApiKey ' \ --header 'accept: application/ld+json '
PHP- cURL
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.netanders.io/v1/utilizations?point=0&type=2&granularity=3&granularitytimezone=1&classification=2&activity=10&validfrom%5Bstrictly_before%5D=2020-11-17&validfrom%5Bafter%5D=2020-11-16',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'X-AUTH-TOKEN: YourSuperSecretApiKey ', ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Python
import requests
url = "https://api.netanders.io/v1/utilizations?point=0&type=2&granularity=3&granularitytimezone=1&classification=2&activity=10&validfrom[strictly_before]=2020-11-17&validfrom[after]=2020-11-16"
payload={}
headers = {
'X-AUTH-TOKEN': ' YourSuperSecretApiKey ',
'accept: application/ld+json '}
response = requests.request("GET", url, headers=headers, data=payload, allow_redirects=False)
print(response.text)
Visualisation snippet
To get an idea of the energy data that is requested, we provide a snippet with which the data can be visualized. The snippet is easy to use in for example Postman, among others. The snippet can be found via this link: https://bitbucket.org/netanders/workspace/snippets/RLpGgL/postman-test-and-visualize
Response to the request
After the request, a result will be returned in the desired file format. The following data is returned:
• Capacity - the average capacity over the selected granularity in kW
• Volume - the production volume in kWh
• Percentage - the utilization rate as a percentage of the total capacity at that moment
• Emission – the emission of CO2 in kg
• Emissionfactor – the emission factor used for this source in kg/kWh, if no value is provided the emission is zero (0)
Tip: for a visualization of the generation it is easiest to use the capacity.
Below the data that is returned by the API. This is a record from the example mentioned.
"@id": "/v1/utilizations/3844522221", "@type": "Utilization", "type": "/v1/types/2", "granularity": "/v1/granularities/3", "granularitytimezone": "/v1/granularity_time_zones/0", "id": 3844522221, "point": "/v1/points/0", "activity": "/v1/activities/1", "classification": "/v1/classifications/2", "capacity": 438626, "volume": 73104, "emission":, "emissionfactor":, "percentage": 0.05968400090932846, "validfrom": "2020-11-16T14:30:00+00:00", "validto": "2020-11-16T14:40:00+00:00", "lastupdate": "2020-11-19T14:06:04+00:00"
Specifics
GranularityTimeZone
The field GranularityTimeZone is used to parse the validfrom and validto entries. When value 0 (UTC) is chosen, the validfrom & validto date in yyyy-MM-dd format is seen as a UTC date. For value 1 (Europe/Amsterdam) otherwise, it is seen likewise.
Furthermore, the datetimes returned by the API are always in UTC.
Also note that aggregations (i.e. day, month, year) are only computed for CET and will only return values for GranularityTimeZone = 1. When GranularityTimeZone = 0 is chosen no values will be returned.
Parameter table
Parameter | Description | Values |
Activity | Gives the activity type of the energy record. | 1 Providing |
Authorisation | Gives the Authorisations for users. | True |
Validfrom[mod] | Data selection, use after, strictly_after, before or strictly_before in place of mod. | Format: YYYY-MM-DD |
Classification | Gives the Classification type of the energy record. (Ex. Near-realtime or Forecast) | 1 Backcast |
Granularity | Every Utilization data record is a grouped by a granularity. This table has the Granularity names. | 3 10 minutes |
GranularityTimeZone | Every Granularity is valid for a certain timezone, this data record holds the name of this timezone. | 0 UTC 1 CET (Central European Time) |
Point | Gives the Point of the energy record. | 0 Nederland |
Type | Gives the Type of the energy resource (for a more detailed description, see https://netanders.atlassian.net/wiki/spaces/PAD/pages/15204353 ). | 0 All 54 IndustrialConsumersPowerGasCombination 55 LocalDistributionCompaniesCombination 56 AllConsumingGas |
Historical data updates
Sometimes historical data provided by the API gets updated. Several triggers exist, which include
changes in the source data
changes in model parameters
changes in the model itself
Whenever a trigger has occurred the ‘lastupdate’ field is modified (note that this does not necessarily mean the interval value itself has changed). Some triggers are periodic (i.e. data gets recomputed daily) and others are manual (recomputation gets done by Nationaal Energie Dashboard’s request).
Any questions, just let us know!