Handleiding API

Hieronder vind je de handleiding voor het toevoegen van de API. We bieden de handleiding ook in het Engels aan. 

Naast de handleiding bieden we ook een algemene uitleg over de API, gedetailleerde omschrijving van de parameters, een changelog en technische documentatie via Swagger UI en Redoc. 

Wat voor type API is het? 

De API is een RESTful OpenApi. De volgende bestandsformaten zijn beschikbaar: jsonld, jsonhal, jsonapi, json, xml, csv en html. 

Toegang tot de API – API sleutel

In jouw account kan je zelf een API-sleutel maken. Deze unieke sleutel geeft toegang tot het opvragen van historische, actuele en voorspellende energiedata. Bij ieder verzoek moet de API-sleutel worden meegestuurd. De API-sleutel is gekoppeld aan jouw account en naam. Verstek de sleutel niet aan anderen. 

API specificaties   

Voor de developers zijn de uitgebreide specificaties van de API via de volgende links te vinden in Swagger UI of Redoc:

• Swagger UI: https://api.ned.nl/v1

• Redoc: https://api.ned.nl/v1?ui=re_doc

Maximaal aantal opvragingen per minuut

De huidige snelheidslimiet van de API is ingesteld op 200 opvragingen per 5 minuten.

Een verzoek indienen 

Bij het in indienen van een verzoek moeten een aantal parameters worden meegegeven. In de onderstaande tabel staat een weergave van de parameters met een beschrijving en de beschikbare parameterwaarden. Voor alle parameters geldt dat er individuele waarden ingegeven kunnen worden of een collectie die verwijst naar een reeks individuele waarden. 

Voorbeeld verzoek 

Stel je wilt de zon opwek van Nederland op 10 minuten ontvangen over 16 november 2020 in json. Hiervoor geef je de volgende parameters mee in het verzoek. Onderstaand staat het voorbeeld verzoek in cURL, PHP-cURL en Python. 

Voor in de header:

Accept: application/ld+json: json – file format.  
X-AUTH-TOKEN: YourSuperSecretApiKey – API Key

Voor in het hoofdbericht:

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.ned.nl/v1/utilizations?point=0&type=2&granularity=3&granularitytimezone=1&classification=2&activity=1&validfrom[strictly_before]=2020-11-17&validfrom[after]=2020-11-16' \
 --header 'X-AUTH-TOKEN: YourSecretApiKey' \
 --header 'accept: application/ld+json '

PHP- cURL

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
 CURLOPT_URL => 'https://api.ned.nl/v1/utilizations?point=0&type=2&granularity=3&granularitytimezone=1&classification=2&activity=1&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: YourSecretApiKey')
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Python

import requests

url = "https://api.ned.nl/v1/utilizations"

headers = {
 'X-AUTH-TOKEN': 'YourSecretApiKey',
 'accept': 'application/ld+json'}
params = {'point': 0, 'type': 2, 'granularity': 3, 'granularitytimezone': 1, 'classification': 2, 'activity': 1,
 'validfrom[strictly_before]': '2020-11-17', 'validfrom[after]': '2020-11-16'}
response = requests.get(url, headers=headers, params=params, allow_redirects=False)

print(response.text)

Visualisatie snippet

Om een beeld te krijgen bij de energiedata die wordt opgevraagd, stellen wij een snippet ter beschikking waarmee de data gevisualiseerd kan worden. De snippet is eenvoudig te gebruiken in o.a. Postman. De snippet is te vinden via deze link.   

De reactie op het verzoek 
Na het verzoek komt er een resultaat terug in het gewenste bestandsformaat. De volgende gegevens worden teruggegeven: 

• Capacity – de gemiddelde capaciteit over de geselecteerde tijdsinterval (granulariteit genoemd) in kW
• Volume – het productievolume in kWh 
• Percentage – de benuttingsgraad in percentage uitgedrukt van de totale capaciteit van dat moment 
• Emission – the emissie van CO₂ in kg.
• Emissionfactor – de emissie factor gebruikt voor de energiedrager in kg/kWh; als er geen waarde wordt opgegeven, is de emissie nul (0). 

Tip: voor een visualisatie van de opwek is het gemakkelijkste om gebruik te maken van de capacity. 

Onderstaand de gegevens die worden teruggegeven door de API. Dit is een record uit het genoemde voorbeeld.            

"@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"

GranularityTimeZone

Het veld GranularityTimeZone wordt gebruikt om de validfrom en validto entries te parsen. Als waarde 0 (UTC) wordt gekozen, wordt de validfrom & validto datum in jjjj-MM-dd formaat gezien als een UTC datum. Bij waarde 1 (Europa/Amsterdam) anders, wordt het op dezelfde manier gezien.

Verder zijn de datetijden die worden geretourneerd door de API altijd in UTC.

Merk ook op dat aggregaties (d.w.z. dag, maand, jaar) alleen worden berekend voor CET en alleen waarden zullen teruggeven voor GranularityTimeZone = 1. Als GranularityTimeZone = 0 wordt gekozen, worden er geen waarden geretourneerd.

Parameter tabel

Historische gegevens bijwerken

Soms worden historische gegevens die door de API worden geleverd, bijgewerkt. Er zijn verschillende triggers, zoals: 

• wijzigingen in de brongegevens;
• veranderingen in modelparameters;
• veranderingen in het model zelf.

Telkens wanneer een trigger optreedt, wordt het veld 'lastupdate' gewijzigd. Dit betekent overigens niet dat de intervalwaarde zelf is gewijzigd. Sommige triggers zijn periodiek (d.w.z. de gegevens worden dagelijks opnieuw berekend) en andere zijn handmatig (herberekenen gebeurt op verzoek van het Nationaal Energie Dashboard).

Heb je vragen, neem contact met ons op.