1. Algemeen
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. Door gebruik te maken van de Open Data Service ga je akkoord met de gebruiksvoorwaarden. Bij verkeerd of oneigenlijk gebruik kunnen we contact opnemen of, in het uiterste geval, de API-key intrekken.
Contact
- Technische vragen? Neem contact op via de Swing helpdesk
- Bij updates informeren we alle geregistreerde gebruikers
2. Technische achtergrond
De Open Data Service maakt gebruik van OData (Open Data Protocol) v4. Hiermee wordt de API op een gestandaardiseerde manier opgebouwd.
- Meer informatie hierover vindt u via https://www.odata.org
- Voorbeeld in Nederland: het CBS maakt ook gebruik van OData
Aanbevolen: JSON-plugin
Gebruik in je browser een plugin zoals JSONView (beschikbaar voor Chrome, Firefox en Edge) om de datastructuur leesbaar weer te geven.
Toegang via andere tools
Je kunt de Open Data Service ook benaderen via tools zoals:
- Microsoft Excel
- Microsoft Power BI
- ETL-tools in GIS-software
- Zelf via code — zie voorbeelden:
Python
import requests url = 'https://voorbeeld-swing.versie.nl/ods/odata/Indicators' 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://voorbeeld-swing.versie.nl/ods/odata/Indicators");
3. Quickstart PowerBI
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://voorbeeld-swing.versie.nl/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 Gegevens transformeren
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://voorbeeld-swing.versie.nl/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.
4. 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://voorbeeld-swing.versie.nl
De beschikbare EntitySets zijn:
- Indicators
- DataCubes
- GeoLevels
- Dimensions
- DimensionLevels
- DataSources
- PeriodLevels
- SwingInfo
- Units
5. Standaardvariabelen en metadata
Hieronder enkele voorbeelden van URL's voor veelgebruikte entiteiten:
SwingInfo
Algemene informatie over de Swing-versie.
https://voorbeeld-swing.versie.nl/ods/odata/SwingInfo
Indicators
Overzicht van alle Indicatoren
https://voorbeeld-swing.versie.nl/ods/odata/Indicators
Metadata van een Indicator
https://voorbeeld-swing.versie.nl/ods/odata/Indicators/wbbevtot
Data combinaties van een kubusindicator.
https://voorbeeld-swing.versie.nl/ods/odata/Indicators/wbbevtot/DataCubes
Data voor een indicator.
https://voorbeeld-swing.versie.nl/ods/odata/Indicators/wbbevtot/Data
GeoLevels
Gebiedsniveaus (GeoLevels).
https://voorbeeld-swing.versie.nl/ods/odata/GeoLevels
Metadata van een gebiedsniveau
https://voorbeeld-swing.versie.nl/ods/odata/GeoLevels/gemeente
Vraag de gebieden van een gebiedsniveau op.
https://voorbeeld-swing.versie.nl/ods/odata/GeoLevels/gemeente/GeoLevelMembers
Dimensions
Dimensie (Dimensons)
https://voorbeeld-swing.versie.nl/ods/odata/Dimensions
Metadata van een dimensie
https://voorbeeld-swing.versie.nl/ods/odata/Dimensions/dim_brandstofklasse_1
DimensionLevels
Dimensieniveau (DimensionLevels)
https://voorbeeld-swing.versie.nl/ods/odata/DimensionLevels
Metadata van een dimensieniveau
https://voorbeeld-swing.versie.nl/ods/odata/DimensionLevels/dnc_alg_lft1
Dimensieniveau-items (DimensionLevelMembers) van een dimensiniveau
https://voorbeeld-swing.versie.nl/ods/odata/DimensionLevels/dnc_alg_lft1/DimensionLevelMembers
PeriodLevels
Periodeniveaus (PeriodLevels).
https://voorbeeld-swing.versie.nl/ods/odata/PeriodLevels
Metadata van een periodeniveau
https://voorbeeld-swing.versie.nl/ods/odata/PeriodLevels/year
Periode-eenheden (PeriodLevelMembers) van een periodeniveau.
https://voorbeeld-swing.versie.nl/ods/odata/PeriodLevels/year/PeriodLevelMembers
Units
Eenheden (Units)
https://voorbeeld-swing.versie.nl/ods/odata/Units
Metadata van een eenheid
https://voorbeeld-swing.versie.nl/ods/odata/Units/aantal
UnitLabels van een eenheid
https://voorbeeld-swing.versie.nl/ods/odata/Units/janee/UnitLabels
DataCubes
Combinaties waarvoor data aanwezig is (DataCubes)
https://voorbeeld-swing.versie.nl/ods/odata/DataCubes
DataCubes voor een Indicator ('kb_gem_verhuisd')
https://voorbeeld-swing.versie.nl/ods/odata/DataCubes/Indicator('kb_gem_verhuisd')
Data van een kubusvariabele
https://voorbeeld-swing.versie.nl /ods/odata/DataCubes(DimensionLevels='',GeoLevel='provincie',Indicator='wbbevtot',Period='year_2015')/Data
DataSources
Databronnen (DataSources)
https://voorbeeld-swing.versie.nl/ods/odata/DataSources
Metadata van een databron
https://voorbeeld-swing.versie.nl/ods/odata/DataSources('abf')
6. 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 handleiding op https://www.odata.org/getting-started/basic-tutorial/.
$filter
Vraag alle databronnen op die de tekst ‘ABF’ bevatten in de naam.
https://voorbeeld-swing.versie.nl/ods/odata/DataSources?$filter=contains(Name, 'ABF')
$select
Vraag alleen de velden Code en Name op.
https://voorbeeld-swing.versie.nl/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://voorbeeld-swing.versie.nl/ods/odata/DataCubes?$skip=200
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