1. Algemeen

In Swing is het mogelijk om data op verschillende manieren handmatig te exporteren. Er is echter steeds meer behoefte om data gestandaardiseerd en geautomatiseerd ophalen.

Om in deze behoefte te voorzien is er een Open Data Service, hierna te noemen ODS, ingesteld. Hiermee kan gestandaardiseerd en geautomatiseerd openbare data worden opgehaald via een API (Application Programming Interface). De Open Data Service moet wel door de beheerder zijn ingeschakeld om hiervan gebruik te maken.

 

Oproep via URL

De ODS wordt via een URL (Uniform Resource Locator) opgeroepen. Binnen deze URL kan met parameters (indicatoren, gebieden, perioden) worden bepaald 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 dataset van de ODS is in JSON formaat.

 

2. Technische achtergrond

De ODS 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 een indruk te geven is er op https://swing.eu/jiveservices/odata/ een openbare versie van de ODS geplaatst.

Deze URL is via de 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 ODS te benaderen vanuit andere programma’s. Via Microsoft Excel, Microsoft Power BI of de ETL-tool in GIS-producten kan verbinding worden gemaakt. Het is daarnaast mogelijk om de ODS zelfstandig te benaderen. Hieronder volgen drie voorbeelden in gangbare programmeertalen:

Python

>>> import requests

>>> url = 'https://swing.eu/jiveservices/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://swing.eu/jiveservices/odata/Variables");

JavaScript

fetch("https://swing.eu/jiveservices/odata/Variables",{ method:"GET", headers: { "apikey": "c19f4d5d-0474-47a0-b2f4-04eef8de4238" }})

.then(function onRes(res){

if (res && res.ok) {

// ..

}

});

 

3. Structuur

Voor gebruik van de ODS is kennis van de datastructuur nodig. Binnen Swing wordt data opgeslagen als 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 ODS 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. In onderstaande voorbeelden wordt de openbare demoversie gebruikt op https://swing.eu/jiveservices/odata.

 

EntitySets

Bij het benaderen van de startpagina van de ODS zijn acht 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://swing.eu/jiveservices/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://swing.eu/jiveservices/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.

 

4. Standaardvariabelen en metadata

Via de ODS kunnen een aantal standaardvariabelen en de bijbehorende metadata worden opgehaald. Hieronder volgt een toelichting van de meest gebruikte combinaties.

 

SwingInfo

Vraag algemene informatie over de Swing-versie op.

Voorbeeld: https://swing.eu/jiveservices/odata/SwingInfo

 

Variables

Vraag de variabelen op.

Voorbeeld: https://swing.eu/JiveServices/odata/Variables

 

DataSources

Vraag de beschikbare databronnen op.

Voorbeeld: https://swing.eu/jiveservices/odata/DataSources

Vraag een enkele databron op.

Voorbeeld: https://swing.eu/jiveservices/odata/DataSources('abf')

Het is ook mogelijk de gegevensbron van een variabele op te vragen.

Voorbeeld: https://swing.eu/JiveServices/odata/Variables('wbbevtot')/DataSources

 

GeoLevels

Vraag de beschikbare gebiedsniveaus op.

Voorbeeld: https://swing.eu/jiveservices/odata/GeoLevels

Het is ook mogelijk de gebiedsniveaus van een variabele op te vragen.

Voorbeeld: https://swing.eu/jiveservices/odata/DataSources('abf')

 

GeoItems

Vraag de beschikbare gebieden binnen een gebiedsniveau op.

Voorbeeld: https://swing.eu/JiveServices/odata/GeoLevels('gemeente')/GeoItems

 

PeriodLevels

Vraag de beschikbare periodeniveaus op.

Voorbeeld: https://swing.eu/JiveServices/odata/PeriodLevels

Het is ook mogelijk om met een variabele en een gebiedsniveau de beschikbare periodeniveaus op te vragen.

Voorbeeld: https://swing.eu/JiveServices/odata/Variables('wbbevtot')/GeoLevels('gemeente')/PeriodLevels

 

Periods

Vraag de beschikbare perioden op.

Voorbeeld: https://swing.eu/JiveServices/odata/Periods

Het is ook mogelijk om met een variabele, een gebiedsniveau en een periodeniveau de beschikbare perioden op te vragen.

Voorbeeld: https://swing.eu/JiveServices/odata/Variables('wbbevtot')/GeoLevels('gemeente16')/PeriodLevels('YEAR')/Periods

 

Values

Vraag de beschikbare waarden op.

Uiteindelijk is het mogelijk om van een variabele met een gebiedsniveau, een periodeniveau en een periode de waarden op te vragen.

Voorbeeld: https://swing.eu/JiveServices/odata/Variables('wbbevtot')/GeoLevels('gemeente16')/PeriodLevels('YEAR')/Periods('2016')/Values

 

5. CubeVariables

 

Kubusvariabelen

Vraag de kubusvariabelen op.

Voorbeeld: https://swing.eu/JiveServices/odata/CubeVariables

Vraag een enkele kubusvariabele op.

Voorbeeld: https://swing.eu/JiveServices/odata/CubeVariables('kb_bev_lft05')

 

Dim-Levels

Omdat de Open Data Service geen volledige lijst met dimensie-items op kan geven, is het mogelijk om de verschillende dimensie members op te vragen. Hiervoor kan je eerst een lijst met mogelijke dimensie niveaus opvragen.

Voorbeeld: https://swing.eu/JiveServices/odata/CubeVariables('kb_bev_lft05')/DimLevels

 

Dim-Members

Met een geldig dimensieniveau kan je een lijst met dimensiemembers opvragen.

Voorbeeld: https://swing.eu/JiveServices/odata/CubeVariables('kb_bev_lft05')/DimLevels('dnc_lft10')/DimMembers

 

Dim-Items

Een dimensieitem is een lijst met dimensiemembers.

Dimensie-items (DimItems) zijn niet opvraagbaar maar wel in te vullen.

Welke dimensie-items er beschikbaar zijn kan je opvragen door middel van DimMembers.

Voorbeeld: https://swing.eu/JiveServices/odata/CubeVariables('kb_bev_lft05')/DimItems('dnc_lft10_1')

 

Values

Uiteindelijk is het mogelijk om van een kubusvariabele met dimensie-item, een gebiedsniveau, een periodeniveau en een periode de waarden op te vragen.

Voorbeeld: https://swing.eu/JiveServices/odata/CubeVariables('kb_bev_lft05')/DimItems('dnc_lft10_1,dnc_gsl_m')/GeoLevels('gemeente16')
/PeriodLevels('YEAR')/Periods('2016')/Values

 

Dimensions

Vraag de beschikbare dimensies op.

Voorbeeld: https://swing.eu/JiveServices/odata/Dimensions

Vraag de dimensieniveaus van een specifieke dimensie op.

Voorbeeld: https://swing.eu/JiveServices/odata/Dimensions('dc_bag_bj')/DimLevels('dnc_bag_bj2')

Vraag de dimensiemembers van een specifiek dimensieniveau op.

Voorbeeld: https://swing.eu/JiveServices/odata/Dimensions('dc_bag_bj')/DimLevels('dnc_bag_bj2')/DimMembers('dnc_bag_bj2_1')

 

6. Aanvullende parameters

Om de data efficiënt op te halen, kan gebruik worden gemaakt van enkele aanvullende parameters. Deze worden hieronder beschreven.

 

Most Recent Period ('mrp')

Met de parameter 'mrp' is het mogelijk om data voor de meeste recente periode op te vragen.

Voorbeeld: https://swing.eu/JiveServices/odata/Variables('wbbevtot')/GeoLevels('gemeente16')/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://swing.eu/JiveServices/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://swing.eu/JiveServices/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 ODS heen gaan om alle gegevens op te halen.

 

OData-queries

De OData v4 structuur ondersteunt een aantal standaard ‘queries’. Hiermee kan de hierboven gedefinieerde uitvragen worden verfijnd, zodat de service geen overbodige data ophaalt. De aanvullende queries die ondersteund worden binnen de ODS 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://swing.eu/jiveservices/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://swing.eu/JiveServices/odata/Variables('wbbevtot')/GeoLevels('all')/PeriodLevels('all')/Periods('all')/Values?$filter=contains(ExternalCode,'buurt16_1680')

 

$select

Vraag alleen de velden ExternalCode en Name op.

Voorbeeld: https://swing.eu/jiveservices/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://swing.eu/JiveServices/odata/GeoLevels('buurt16')/GeoItems?$skip=1000

 

7. Gebruik met Microsoft Power BI

De Open Data Service sluit naadloos aan op de data visualisatie functionaliteiten binnen Power BI. Hieronder volgen enkele voorbeelden om het gebruik te vereenvoudigen.

 

Query's

Power BI gebruikt query's om data uit de Open Data Service te halen. Hierbij is de URL om de data op te halen hetzelfde als in de browser met een kleine toevoeging eromheen.

Voorbeeld: = OData.Feed("https://swing.eu/jiveservices/odata/Variables")

 

Uitzonderingen

Bij specifieke query's kan het zijn dat Power BI meldt dat de databron niet kan worden gevonden [Error 404], wanneer deze databron wel bestaat kan deze alsnog worden opgehaald. Dit kan door middel van de in hoofdstuk 6 gebruikte manier van data ophalen met de ?$top= functie met een arbitrair hoge waarde als parameter.

Voorbeeld: = OData.Feed("https://swing.eu/jiveservices/odata/Variables?$top=10000")