Swing API - Open Data Service

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.

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.

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.

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:

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

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

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

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.

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.

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.

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

Vraag algemene informatie over de Swing-versie op.

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

Vraag de variabelen op.

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

Vraag de beschikbare databronnen op.

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

Vraag een enkele databron op.

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

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

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

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/GeoLevels('abf')

Vraag de beschikbare gebieden binnen een gebiedsniveau op.

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

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

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

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

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')

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

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

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')

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

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')

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

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

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

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.

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.

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/.

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')

Vraag alleen de velden ExternalCode en Name op.

Voorbeeld: https://swing.eu/jiveservices/odata/Variables?$select=ExternalCode,Name

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

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

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

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