1. Algemeen
Met de Open Data Service kan gestandaardiseerd en geautomatiseerd openbare data uit een Swing-applicatie worden opgehaald via een API (Application Programming Interface). De Open Data Service moet door de beheerder in Swing zijn ingeschakeld om gebruikers ervan gebruik te kunnen laten maken.
Oproep via URL
De Open Data Service wordt benaderd via een URL (Uniform Resource Locator). Binnen deze URL geef je met parameters aan welke gegevens je wilt ophalen. Omdat de structuur vastligt, krijg je bij elke oproep dezelfde datavorm terug. De data wordt geleverd in JSON-formaat.
API-key
Voor authenticatie is een persoonlijke API-key nodig. Deze moet bij elke request worden meegestuurd. Bij verkeerd of oneigenlijk gebruik kunnen we contact opnemen of, in het uiterste geval, de API-key van de betreffende gebruiker intrekken.
2. Technische achtergrond
De Open Data Service maakt gebruik van OData (Open Data Protocol) v4. Hiermee wordt de API op een gestandaardiseerde manier opgebouwd. In Nederland maakt het Centraal Bureau voor de Statistiek bijvoorbeeld gebruik van deze standaard. Meer informatie hierover vindt je op https://www.odata.org.
In deze handleiding gebruiken we de openbare Swing demo als voorbeeld van een Swing database van waaruit data opgehaald kan worden, zie https://demo.swingsoftware.eu/ods/odata. Gebruik in je browser een plugin zoals JSONView (beschikbaar voor Chrome, Firefox en Edge) om de datastructuur leesbaar weer te geven.
Naast de browser is het mogelijk om de Open Data Service te benaderen vanuit andere programma's, zoals:
- Microsoft Excel
- Microsoft Power BI (aangezien dit een veelgebruikt platform is, gaan we hier in Hoofdstuk 7 dieper op in.
- ETL-tools in GIS-software
- Zelf via code — zie voorbeelden:
Python
import requests url = 'https://demo.swingsoftware.eu/ods/odata/Indicators' headers = {'apikey': '31140a27-bd73-43ca-a597-14cc42e791e0'} r = requests.get(url, headers=headers)
C#
using System.Net; var wc = new WebClient(); wc.Headers.Add("apikey", "31140a27-bd73-43ca-a597-14cc42e791e0"); wc.DownloadString("https://demo.swingsoftware.eu/ods/odata/Indicators");
3. Structuur
Basis-URL
Iedere ODS-versie heeft een vaste basis-URL. Deze URL komt terug in alle aanroepen die gedaan worden.
EntitySets
Bij het benaderen van de startpagina van de Open Data Service zijn 9 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 te benaderen door deze achter de basis-URL te plaatsen, bijvoorbeeld
https://demo.swingsoftware.eu.
De beschikbare EntitySets zijn:
- Indicators
- DataCubes
- GeoLevels
- Dimensions
- DimensionLevels
- DataSources
- PeriodLevels
- SwingInfo
- Units
4. Standaardvariabelen en metadata
Hieronder enkele voorbeelden van URL's voor veelgebruikte entiteiten:
Indicators
Overzicht van alle Indicatoren
https://demo.swingsoftware.eu/ods/odata/Indicators
Metadata van een Indicator
https://demo.swingsoftware.eu/ods/odata/Indicators/bevtot
Data combinaties van een kubusindicator.
https://demo.swingsoftware.eu/ods/odata/Indicators/kb_bag_w/DataCubes
Data voor een indicator.
https://demo.swingsoftware.eu/ods/odata/Indicators/bevtot/Data
GeoLevels
Gebiedsniveaus (GeoLevels).
https://demo.swingsoftware.eu/ods/odata/GeoLevels
Metadata van een gebiedsniveau
https://demo.swingsoftware.eu/ods/odata/GeoLevels/gemeente
Vraag de gebieden van een gebiedsniveau op.
https://demo.swingsoftware.eu/ods/odata/GeoLevels/gemeente/GeoLevelMembers
Dimensions
Dimensie (Dimensons)
https://demo.swingsoftware.eu/ods/odata/Dimensions
Metadata van een dimensie
https://demo.swingsoftware.eu/ods/odata/Dimensions/dc_alg_lft
DimensionLevels
Dimensieniveau (DimensionLevels)
https://demo.swingsoftware.eu/ods/odata/DimensionLevels
Metadata van een dimensieniveau
https://demo.swingsoftware.eu/ods/odata/DimensionLevels/dnc_alg_lft1
Dimensieniveau-items (DimensionLevelMembers) van een dimensiniveau
https://demo.swingsoftware.eu/ods/odata/DimensionLevels/dnc_alg_lft1/DimensionLevelMembers
PeriodLevels
Periodeniveaus (PeriodLevels).
https://demo.swingsoftware.eu/ods/odata/PeriodLevels
Metadata van een periodeniveau
https://demo.swingsoftware.eu/ods/odata/PeriodLevels/year
Periode-eenheden (PeriodLevelMembers) van een periodeniveau.
https://demo.swingsoftware.eu/ods/odata/PeriodLevels/year/PeriodLevelMembers
Units
Eenheden (Units)
https://demo.swingsoftware.eu/ods/odata/Units
Metadata van een eenheid
https://demo.swingsoftware.eu/ods/odata/Units/aantal
UnitLabels van een eenheid
https://demo.swingsoftware.eu/ods/odata/Units/sted/UnitLabels
DataCubes
Combinaties waarvoor data aanwezig is (DataCubes)
https://demo.swingsoftware.eu/ods/odata/DataCubes
DataCubes voor een Indicator
https://demo.swingsoftware.eu/ods/odata/DataCubes/Indicator/kb_bag_w
Data van een kubusvariabele
https://demo.swingsoftware.eu/ods/odata/DataCubes(Dimensionlevels='',GeoLevel='gemeente',Indicator='bevtot',Period='year_2015')/Data
DataSources
Databronnen (DataSources)
https://demo.swingsoftware.eu/ods/odata/DataSources
Metadata van een databron
https://demo.swingsoftware.eu/ods/odata/DataSources/abf_bgsm
SwingInfo
Algemene informatie over de Swing-versie. Deze entiteit is alleen op te roepen wanneer er een settings file is geplaatst. ABF kan dit op verzoek doen.
https://demo.swingsoftware.eu/ods/odata/SwingInfo
5. Aanvullende parameters
OData-queries
Gebruik standaard OData v4-queryparameters om uitvragen te verfijnen:
- $filter
- $select
- $skip
Plaats deze queries achter de hierboven gedefinieerde URL’s. Hiermee is het 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.
Meer informatie staat in de OData-handleiding.
$filter
Vraag alle databronnen op die de tekst ‘ABF’ bevatten in de naam.
https://demo.swingsoftware.eu/ods/odata/DataSources?$filter=contains(Name, 'ABF')
$select
Vraag alleen de velden Code en Name op.
https://demo.swingsoftware.eu/ods/odata/Indicators?$select=Code,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.
@odata.nextLink
Voor sommige EntitySets is een beperking ingesteld voor het aantal op te halen items. In dat geval wordt automatisch een item ‘@odata.nextLink toegevoegd aan het verzoek. Hiermee kan een gevorderde gebruiker makkelijk Open Data Service gebruiken om alle gegevens op te halen.
https://demo.swingsoftware.eu/ods/odata/DataCubes?$skip=200
7. Quickstart PowerBI
Aangezien Power BI veel als platform voor het ophalen en verwerken van data gebruikt wordt, gaan we in dit laatste hoofdstuk specifiek in op hoe Power BI te koppelen met de Open Data Service. Power BI ondersteunt standaard geen API-keys in OData-feeds. Volg deze stappen om de ODS toch te koppelen:
Stap 1: OData-feed toevoegen
- Open Power BI
- Klik op Gegevens ophalen → OData-feed
Stap 2: Voer de URL in
- Vul de ODS-URL in, zoals https://demo.swingsoftware.eu/ods/odata)
- Kies bij verificatie Anoniem en bevestig met dezelfde URL
Stap 3: Objecttype selecteren
- Selecteer bijvoorbeeld Indicators
- De voorbeeldweergave (preview) blijft waarschijnlijk leeg – dat is normaal
- Selecteer Laden of Gegevenstransformeren
Stap 4: Geavanceerde editor openen
- Klik in de rechter zijbalk (Queries) met de rechtermuisknop op de zojuist gemaakte query
- Kies Geavanceerde editor
De geavanceerde editor ziet er als volgt uit:
Stap 5: API-key toevoegen aan de query
Vervang de standaardcode met onderstaande (vul je eigen API-key in):
let Bron = OData.Feed("https://demo.swingsoftware.eu/ods/odata/", null, [Implementation="2.0",Headers = [#"ApiKey" = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]]), Indicators_table = Bron{[Name="Indicators",Signature="table"]}[Data] in Indicators_table
Daarna wordt de data correct opgehaald in Power BI.
Was dit artikel nuttig?
Dat is fantastisch!
Hartelijk dank voor uw beoordeling
Sorry dat we u niet konden helpen
Hartelijk dank voor uw beoordeling
Feedback verzonden
We stellen uw moeite op prijs en zullen proberen het artikel te verbeteren