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