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:
>>> 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.
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.
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')
Alle mogelijkheden uit één EntitySet ('all')
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:
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/.