Open Data Service 2.0

Gewijzigd op Vr, 20 Jun om 1:00 PM

1. Algemeen

Oproep via URL

De Open Data Service wordt opgeroepen via een URL (Uniform Resource Locator). Binnen deze URL geeft u met parameters aan 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 teruggave van de Open Data Service is in JSON formaat.

API-key

Om de Open Data Service te kunnen gebruiken heeft een gebruiker ter authenticatie een API-key nodig. Deze moet bij elke request meegegeven worden. Bij gebruik van de Open Data Service gaat u akkoord met onze gebruiksvoorwaarden. Bij verkeerd gebruik of misbruik van de API nemen we contact met u op. In het uiterste geval trekken we de API-key in.

Contact

Technische vragen over de Open Data Service kunt u stellen via [Helpdesk email]. Voor inhoudelijke vragen over de data gebruikt u het contactformulier. Wanneer we nieuws hebben over de Open Data Service, stellen we alle gebruikers op de hoogte.

2. Technische achtergrond

De Open Data Service 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 u een indruk te geven hebben we op https://accept-wsjg.databank.nl/ods/odata een openbare versie van de Open Data Service geplaatst. Deze URL is via uw 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 Open Data Service te benaderen vanuit andere programma’s. Via Microsoft Excel, Microsoft Power BI of de ETL-tool in GIS-producten kunt u verbinding maken. Het is daarnaast mogelijk om de Open Data Service zelfstandig te benaderen. Onderstaand geven we twee voorbeelden in gangbare programmeertalen weer.

Python

    import requests
    url = 'https://accept-wsjg.databank.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://accept-wsjg.databank.nl/ods/odata/Indicators");

3. Quickstart PowerBI

Om toegang te krijgen tot de Open Data Service van Swing is een API-key nodig voor authenticatie. Omdat Power BI standaard geen makkelijke manier biedt om een API-key toe te voegen aan een OData-feed, volgt hier een korte handleiding om dit toch mogelijk te maken.

Stap 1: OData-feed toevoegen

Open Power BI.
Klik op Gegevens ophalen → OData-feed.

Stap 2: URL invoeren

Voer de URL van de Swing ODS in (bijvoorbeeld: https://accept-wsjg.databank.nl/ods/odata) en klik op OK.
Als dit de eerste keer is dat je verbinding maakt, krijg je een venster om de verbindingsmethode te kiezen:
- Selecteer Anoniem.
- Voer opnieuw dezelfde URL in als hierboven.
- Klik op Verbinding maken.

Stap 3: Objecttype selecteren

Kies het gewenste objecttype (bijvoorbeeld Indicators).
De voorbeeldweergave (preview) blijft waarschijnlijk leeg – dat is normaal.
3. Klik op Laden of Gegevens transformeren om door te gaan.

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

Voeg de dikgedrukte tekst toe uit onderstaande teksblok toe met op de plaats van ‘xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’ jouw Api-key en klik vervolgens op Gereed. N.B. dat jouw API-key anders samengesteld kan zijn.

let
    Bron = OData.Feed("https://accept-wsjg.databank.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

Hierna zal er in Power BI wel data verschijnen.

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 aanroepbaar door deze achter de basis-URL te plaatsen, bijvoorbeeld https://accept-wsjg.databank.nl/ods/odata/Indicators. De beschikbare EntitySets zijn:

Indicators
DataCubes
GeoLevels
Dimensions
DimensionLevels
DataSources
PeriodLevels
SwingInfo
Units

5. Standaardvariabelen en metadata

Via de Open Data Service kunt u een aantal standaardvariabelen en de bijbehorende metadata ophalen. We lichten de meest gebruikte combinaties hieronder toe.

SwingInfo

Vraag algemene informatie over de Swing-versie op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/SwingInfo

Indicators

Vraag de Indicators op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/Indicators

Vraag een enkele Indicator (wbbevtot) op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/Indicators/wbbevtot

Vraag de beschikbare combinaties data (DataCubes) voor een indicator op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/Indicators/wbbevtot/DataCubes

Vraag de beschikbare data voor een indicator op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/Indicators/wbbevtot/Data

GeoLevels

Vraag de beschikbare gebiedsniveaus(GeoLevels) op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/GeoLevels

Vraag een enkele GeoLevel op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/GeoLevels/gemeente

Vraag de gebieden (GeoLevelMembers) van een GeoLevel op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/GeoLevels/gemeente/GeoLevelMembers

Dimensions

Vraag de beschikbare Dimensons op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/Dimensions

Vraag een enkele Dimension op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/Dimensions/dim_brandstofklasse_1

DimensionLevels

Vraag de beschikbare DimensionLevels op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DimensionLevels

Vraag een enkel DimensionLevel op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DimensionLevels/dnc_alg_lft1

Vraag de DimensionLevelMembers van een DimensionLevel op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DimensionLevels/dnc_alg_lft1/DimensionLevelMembers

PeriodLevels

Vraag de beschikbare periodeniveaus (PeriodLevels) op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/PeriodLevels

Vraag een enkel PeriodLevel op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/PeriodLevels/year

Vraag de PeriodLevelMembers van een PeriodLevel op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/PeriodLevels/year/PeriodLevelMembers

Units

Vraag de beschikbare eenheden (Units) op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/Units

Vraag een enkele Unit op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/Units/aantal

Vraag de UnitLabels van een Unit op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/Units/janee/UnitLabels

DataCubes

Vraag de beschikbare combinaties waarvoor data aanwezig is (DataCubes) op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DataCubes

Vraag de DataCubes voor een Indicator ('wbbevtot') op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DataCubes/Indicator('kb_gem_verhuisd')

Vraag de Data van een DataCubes op. (indicator:wbbevtot, gebiedsniveau: provincie, periode: 2015)

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DataCubes(DimensionLevels='',GeoLevel='provincie',Indicator='wbbevtot',Period='year_2015')/Data

DataSources

Vraag de beschikbare databronnen (DataSources) op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DataSources

Vraag een enkele DataSources op.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DataSources('abf')

6. Aanvullende parameters

OData-queries

De OData v4 structuur ondersteunt een aantal standaard ‘queries’. Hiermee kunt u de hierboven gedefinieerde uitvragen verfijnen, zodat de service geen overbodige data ophaalt. De aanvullende queries die ondersteund worden binnen de Open Data Service 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:

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DataSources?$filter=contains(Name, 'ABF')

$select

Vraag alleen de velden Code en Name op.

Voorbeeld: https://accept-wsjg.databank.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. Als dit het geval is wordt automatisch een item ‘@odata.nextLink toegevoegd aan de vraag. Hiermee kan een gevorderde gebruiker makkelijk door Open Data Service heen gaan om alle gegevens op te halen.

Voorbeeld: https://accept-wsjg.databank.nl/ods/odata/DataCubes?$skip=200