Open Data Service 2.0

Gewijzigd op Ma, 23 Jun om 6:24 PM

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

Open 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

Voer de URL in

Stap 3: Objecttype selecteren

  • Selecteer bijvoorbeeld Indicators
  • De voorbeeldweergave (preview) blijft waarschijnlijk leeg – dat is normaal
  • Selecteer Laden of Gegevens transformeren

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

Selecteer geavanceerde editor

De geavanceerde editor ziet er als volgt uit:

Pagina geavanceerde editor

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.

Resultaat 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

Laat ons weten hoe we dit artikel kunnen verbeteren!

Selecteer tenminste een van de redenen
CAPTCHA-verificatie is vereist.

Feedback verzonden

We stellen uw moeite op prijs en zullen proberen het artikel te verbeteren