• Home
  • Handleiding Open Data Service

Handleiding Open Data Service

1. Algemeen

In de Regionale klimaatmonitor is het mogelijk om data op verschillende manieren handmatig te exporteren. Sommige gebruikers willen echter data gestandaardiseerd en geautomatiseerd ophalen. 
 

Daarom hebben we een Open Data Service (ODS) ingesteld op de Regionale klimaatmonitor. Hiermee kunt u gestandaardiseerd en geautomatiseerd openbare data uit de Regionale klimaatmonitor ophalen via een API (Application Programming Interface).

Oproep via URL

De Open Data Service wordt opgeroepen via een URL (Uniform Resource Locator). Binnen deze URL geeft u met parameters (indicatoren, gebieden, perioden) aan welke selectie van gegevens opgehaald moet worden. Op deze manier is een URL toekomstbestendig en zal deze bij iedere oproep de data in een identieke structuur terug geven. De teruggave van de Open Data Service is in JSON formaat.

API-key

Om de Open Data Service te kunnen gebruiken heeft een gebruiker ter authenticatie een API-key nodig. Deze moet bij elke request meegegeven worden. U kunt de API-key via het contactformulier op de Regionale klimaatmonitor-website aanvragen. Hierbij vragen wij uw naam, organisatie en mailadres. Deze gebruiken we uitsluitend voor het registreren van de API-key en communicatie over de Open Data Service.

Bij gebruik van de Open Data Service gaat u akkoord met onze gebruiksvoorwaarden. Bij verkeerd gebruik of misbruik van de API nemen we contact met u op. In het uiterste geval trekken we de API-key in.

Contact

Technische vragen over de Open Data Service kunt u stellen via Klimaatmonitor@abf.nl. Voor inhoudelijke vragen over de data gebruikt u het contactformulier. Wanneer we nieuws hebben over de Open Data Service, stellen we alle gebruikers op de hoogte.

⬆ Terug naar het begin 

2. Technische achtergrond

De Open Data Service maakt gebruik van OData (Open Data Protocol) v4. Dit is een internationale standaard waarmee een API volgens een vast model gedefinieerd kan worden. 

 

Meer informatie hierover vindt u via https://www.odata.org. Binnen Nederland maakt bijvoorbeeld het Centraal Bureau voor de Statistiek ook gebruik van deze standaard.

Om u een indruk te geven hebben we op https://demo.swingsoftware.eu/viewerservices/odata/ een openbare versie van de Open Data Service geplaatst. Deze URL is via uw browser benaderbaar en toont de structuur van de gegevens zoals deze opgehaald worden. We raden aan om hiervoor een plug-in in uw browser te gebruiken, zoals JSONView (beschikbaar in Google Chrome, Mozilla Firefox en Microsoft Edge), zodat de structuur goed leesbaar is.

Om het ophalen van de data gebruiksvriendelijker te maken, bieden we vanaf medio oktober 2021 een openbare API-client ‘SwingODS’ aan. Hiermee kan een gebruiker met Python eenvoudig de gewenste data ophalen.

Het is ook mogelijk om de Open Data Service te benaderen vanuit andere programma’s. Via Microsoft Excel, Microsoft Power BI of de ETL-tool in GIS-producten kunt u verbinding maken. Het is daarnaast mogelijk om de Open Data Service zelfstandig te benaderen. Onderstaand geven we drie voorbeelden in gangbare programmeertalen weer.

Python

>>> import requests 
>>> url = 'https://demo.swingsoftware.eu/viewerservices/odata/Variables' 
>>> headers = {'apikey': 'c19f4d5d-0474-47a0-b2f4-04eef8de4238'} 
>>> r = requests.get(url, headers=headers)

C#

using System.Net; 
var wc = new WebClient(); 
wc.Headers.Add("apikey", "c19f4d5d-0474-47a0-b2f4-04eef8de4238"); 
wc.DownloadString("https://demo.swingsoftware.eu/viewerservices/odata/Variables");

JavaScript

fetch("https://demo.swingsoftware.eu/viewerservices/odata/Variables",{ method:"GET", headers: { "apikey": "c19f4d5d-0474-47a0-b2f4-04eef8de4238" }}) 
.then(function onRes(res){ 
    if (res && res.ok) { 
         // .. 
     } 
});

⬆ Terug naar het begin 

3. Structuur

Voor gebruik van de Open Data Service is kennis van de datastructuur zoals we deze hanteren in de Regionale klimaatmonitor nodig. Binnen de Regionale klimaatmonitor slaan we data op als een combinatie van indicator, gebied en periode. 

 

Iedere unieke combinatie van deze parameters resulteert in de data horend bij een specifiek onderwerp, voor een specifiek gebied en een specifieke periode.

De Open Data Service gebruikt deze parameters om de gewenste data op te halen. Deze zijn onderdeel van de URL die aangeroepen wordt. Deze beschikbare parameters zijn los ook benaderbaar via de ODS.

Basis-URL

Iedere ODS-versie heeft een vaste basis-URL. Deze URL komt terug in alle aanroepen die gedaan worden. Voor de Regionale klimaatmonitor is dit https://klimaatmonitor.databank.nl/jiveservices/odata. Omdat de Open Data Service gekoppeld aan de Regionale klimaatmonitor niet openbaar beschikbaar is, maken we in onderstaande voorbeelden gebruik van de openbare demoversie op https://demo.swingsoftware.eu/viewerservices/odata. De werking hiervan is identiek aan de Regionale klimaatmonitor ODS.

EntitySets

Bij het benaderen van de startpagina van de Open Data Service zijn 8 verschillende ‘EntitySets’ zichtbaar. Een Entityset is een verzameling unieke items (Entities) die overeenkomstige kenmerken hebben. Dit zijn bijvoorbeeld eerder genoemde indicatoren, gebieden of perioden. De EntitySets zijn aanroepbaar door deze achter de basis-URL te plaatsen, bijvoorbeeld https://demo.swingsoftware.eu/viewerservices/odata/Variables. De beschikbare EntitySets zijn:

  • Variables
  • GeoLevels
  • GeoItems
  • PeriodLevels
  • Periods
  • Values
  • DataSources
  • SwingInfo

Een deel van deze EntitySets is direct aan te roepen (bijv. Variables), terwijl anderen alleen aanroepbaar zijn in combinatie met een andere EntitySet. Een voorbeeld hiervan is GeoItems: deze kan alleen aangeroepen worden in combinatie met een gedefinieerde Entity uit GeoLevels.

Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/GeoLevels('gemeente')/GeoItems

Wanneer een specifieke Entity opgehaald wordt, staat deze tussen haakjes benoemd achter de EntitySet. In dit voorbeeld worden de items van EntitySet ‘Geoitems’ voor Entity ‘gemeente’ uit EntitySet ‘GeoLevel’ opgehaald. Dit geldt ook voor het ophalen van data, waarbij u een combinatie van Variables, GeoLevels, PeriodLevels en Periods moet definieren.

⬆ Terug naar het begin 

4. Standaardvariabelen en metadata

Via de Open Data Service kunt u een aantal standaardvariabelen en de bijbehorende metadata ophalen. We lichten de meest gebruikte combinaties hieronder toe.

SwingInfo

Vraag algemene informatie over de Swing-versie op (Swing is het softwarepakket waarop de Regionale klimaatmonitor draait). 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/SwingInfo

Variables

Vraag de variabelen op. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables

Vraag een enkele variabele op. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')

DataSources

Vraag de beschikbare databronnen op. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/DataSources

Vraag een enkele databron op.
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/DataSources('abf_bgsm') 

Het is ook mogelijk de gegevensbron van een variabele op te vragen. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')/DataSource 

GeoLevels

Vraag de beschikbare gebiedsniveaus op. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/GeoLevels

Het is ook mogelijk de gebiedsniveaus van een variabele op te vragen.
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')/GeoLevels

GeoItems

Vraag de beschikbare gebieden binnen een gebiedsniveau op. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/GeoLevels('gemeente')/GeoItems

PeriodLevels

Vraag de beschikbare periodeniveaus op.
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/PeriodLevels

Het is ook mogelijk om met een variabele en een gebiedsniveau de beschikbare periodeniveaus op te vragen. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')/GeoLevels('gemeente')/PeriodLevels

Periods

Vraag de beschikbare perioden op. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Periods

Het is ook mogelijk om met een variabele, een gebiedsniveau en een periodeniveau de beschikbare perioden op te vragen. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')/GeoLevels('gemeente')/PeriodLevels('YEAR')/Periods

Values

Vraag de beschikbare waarden op.

Uiteindelijk is het mogelijk om van een variabele met een gebiedsniveau, een periodeniveauen een periode de waarden op te vragen.
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')/GeoLevels('gemeente')/PeriodLevels('YEAR')/Periods('2016')/Values

⬆ Terug naar het begin 

5. Aanvullende parameters

Om de data efficiënt op te halen, kunt u gebruik maken van enkele aanvullende parameters. Deze beschrijven we onderstaand.

Most Recent Period ('mrp')

Met de parameter 'mrp' is het mogelijk om data voor de meeste recente periode op te vragen. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')/GeoLevels('gemeente')/PeriodLevels('year')/Periods('mrp')/Values

Alle mogelijkheden uit één EntitySet ('all')

Met de parameter 'all' is het mogelijk om data ongefilterd op te vragen. Deze kan toegepast worden op EntitySets GeoLevels, PeriodLevels en Periods.

Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')/GeoLevels('all')/PeriodLevels('all')/Periods('all')/Values

Wanneer parameter 'PeriodLevels' de waarde 'all' heeft wordt de waarde van parameter 'Periods' genegeerd. In dat geval worden waarden teruggegeven voor alle beschikbare perioden.

Uitzondering hierop is parameter 'mrp'. Bij gebruik van parameter 'mrp' bevat het resultaat per combinatie van gebiedsniveau en periodeniveau alleen data voor de meeste recente periode.

Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')/GeoLevels('all')/PeriodLevels('all')/Periods('mrp')/Values

@odata.navigationlink

Sommige EntitySets zijn onherroepelijk verbonden, zoals GeoLevels en GeoItems. Om navigatie hierin makkelijker te maken bevatten alle Entities hierin een navigationlink naar onderliggende Entitysets. Deze is herkenbaar doordat deze start met de gerelateerde Entityset en eindigt met @odata.navigationlink.

@odata.nextLink

Voor sommige EntitySets is een beperking ingesteld voor het aantal op te halen items. Als dit het geval is wordt automatisch een item ‘@odata.nextLink toegevoegd aan de vraag. Hiermee kan een gevorderde gebruiker makkelijk door Open Data Service heen gaan om alle gegevens op te halen.

OData-queries

De OData v4 structuur ondersteunt een aantal standaard ‘queries’. Hiermee kunt u de hierboven gedefinieerde uitvragen verfijnen, zodat de service geen overbodige data ophaalt. De aanvullende queries die ondersteund worden binnen de Open Data Service zijn de volgende:

  • $filter
  • $select
  • $skip

Deze queries plaatst u achter de hierboven gedefinieerde URL’s. Hiermee is het bijvoorbeeld mogelijk om variabelen te filteren op naam, of alleen de buurten op te halen voor één specifieke gemeente.

De queries beginnen altijd met een dollarteken en zijn gescheiden van de URL door een vraagteken. In de voorbeelden hieronder tonen we slechts een beperkte selectie van de mogelijkheden. Meer informatie vindt u in de handleiding op https://www.odata.org/getting-started/basic-tutorial/.

$filter

Vraag alle databronnen op die de tekst ‘ABF’ bevatten in de naam.
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/DataSources?$filter=contains(Name, 'ABF')

Vraag alle buurtdata voor indicator Bevolking-totaal op, waarvan de code ‘_1680’ bevat. Dit zijn alle buurten binnen gemeente Aa en Hunze. 
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables('bevtot')/GeoLevels('all')/PeriodLevels('all')/Periods('all')/Values?$filter=contains(ExternalCode,'buurt22_1680')

$select

Vraag alleen de velden ExternalCode en Name op.
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/Variables?$select=ExternalCode,Name

$skip

Bij sommige EntitySets wordt een beperkt aantal Entities getoond. Wanneer deze limiet bereikt is wordt aan het einde van het verzoek een @odata.nextlink geplaatst. Deze kan ook handmatig gegenereerd worden door $skip te gebruiken.
Voorbeeld: https://demo.swingsoftware.eu/viewerservices/odata/GeoLevels('buurt22')/GeoItems?$skip=1000 

⬆ Terug naar het begin