Swing API - Open Data Service 2.0

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.