search

provinciesincijfers / PinC-taakopvolging

Dagelijks werk aan provincies.incijfers.be door de medewerkers van Data & Analyse
1 stars 1 forks source link

Handleiding PinC Open Data Service #451

Closed GeertBonte closed 5 months ago

GeertBonte commented 7 months ago

Ik heb op vraag van @HildeC een handleiding gemaakt voor de PinC Open Data Service (ODS). Ik heb een voorlopige versie van het document geüpload naar de bèta-versie: https://beta-provincies.incijfers.be/admin/jive/report/?id=handleiding_ods

De handleiding is gebaseerd op de ODS-handleiding van ABF, maar dan aangepast voor PinC. De voorbeelden in de ABF-handleiding werken met een API-key en geven Nederlandse resultaten. Bij PinC gebruiken we geen API-key, dus dat stukje heb ik weggelaten. Bij alle voorbeeldlinks in mijn handleiding wordt gebruik gemaakt van de databank van provincies.incijfers.be (en niet van de Nederlandse data uit de ABF-handleiding).

@SarahMeire heeft de handleiding al nagekeken en enkele suggesties gedaan die ik graag ter harte neem. Ik zal nog een extra stukje toevoegen waarin met enkele concrete voorbeelden gedemonstreerd wordt hoe je de ODS kunt gebruiken met Python.

Voor de niet-ingewijden: de Open Data Service van PinC is een webservice waarmee aan de hand van een industriestandaard (het Open Data Protocol of OData v4) informatie uit de databank van PinC ter beschikking gesteld wordt van het publiek. Gebruikers kunnen op die manier data opvragen in hun eigen toepassingsprogramma's (bv. Python-scripts of toepassingen in andere programmeertalen) of met andere software die het gebruik van OData ondersteunt (bv. Excel, Power BI, FME, etc.). Op die manier is het mogelijk om het (periodiek) ophalen van data uit PinC te automatiseren.

Het hoofdstukje waarin het gebruik van de ODS met Excel toegelicht wordt, heb ik volledig zelf geschreven en komt dus niet uit de handleiding van ABF. Samen met @HildeC ben ik van mening dat heel wat gebruikers, die niet kunnen of willen programmeren, hier zeker iets aan zullen hebben.

Emilien-Dupont commented 6 months ago

RG 25/04/24: Feedback kan gegeven worden tegen de Redactiegroep van 23/05

Emilien-Dupont commented 6 months ago

Het ziet er heel erg mooi en duidelijk uit! Een klein puntje: je geeft als voorbeeld van een enkele databron: https://provincies.incijfers.be/jiveservices/odata/DataSources('dna_wijkindeling') op. Maar de dna_wijkindeling is misschien geen goed voorbeeld van een databron, aangezien het niet echt een typische databron is.

Ik weet niet of het hier thuis hoort, maar het kan voor een gebruiker ook makkelijk zijn dat er kort een toelichting komt waar ze de codes voor de indicatoren juist kunnen terugvinden (rechtermuisknop op de indicator klikken > informatie over de indicator > tab ‘Eigenschappen’).

GeertBonte commented 6 months ago

Ik heb een hoofdstuk toegevoegd met concrete voorbeelden hoe je de ODS kunt gebruiken met Python. Alle suggesties tot verbetering zijn welkom.

Emilien-Dupont commented 5 months ago

RG 23/05/24: feedback kan nog gegeven worden tot 31/05, daarna wordt het extern geplaatst. het stuk 'Data services' vervalt en verwijst door naar nieuwe pagina (zie themaboom) https://provincies.incijfers.be/dashboard/dashboard/gebruik-van-de-website : hier de handleiding aan toevoegen (in de tegel 'Handleiding'): Handleiding / open data service

Emilien-Dupont commented 5 months ago

De handleiding werd toegevoegd aan de themaboom en er werd naar verwezen op de bovenvernoemde plaatsen.

emdockx commented 3 months ago

@GeertBonte , weet jij of je via de ODS meerdere indicatoren tegelijk kan opvragen? Bijvoorbeeld: v1101_t en v1111a_tot_bevolking. Twee variabele codes meegeven in eenzelfde URL lukt mij voorlopig niet. Ik vind hierover ook niet meteen iets terug in de handleiding. Misschien kan het gewoonweg niet? Een omweggetje door meerdere requests te sturen (één per variabele) lukt natuurlijk wel.

EDIT: En op eenzelfde manier vraag ik mij ook af of je bv. enkel periode 2020-2023 kan opvragen (in plaats van gebruik te maken van "all" of vier aparte requests te sturen).

GeertBonte commented 3 months ago

Neen, bij mijn weten kun je maar één indicator opvragen. Als je er meerdere nodig hebt, moet je ze apart opvragen. Wat de perioden betreft: ook hier maar één periode, of allemaal met 'all'.

GeertBonte commented 3 days ago

EDIT: En op eenzelfde manier vraag ik mij ook af of je bv. enkel periode 2020-2023 kan opvragen (in plaats van gebruik te maken van "all" of vier aparte requests te sturen).

Bij nader inzien is dit mogelijk met één request. Je vraagt daartoe alle periodes op met Periods('all'), en je voegt op het einde van de URL deze query toe:

?$filter=Period ge '2020' and Period le '2023'

De aanvankelijke resultaten (alle perioden) worden dan gefilterd. Enkel de records waarvan de inhoud van 'Period' groter of gelijk is aan '2020' én kleiner of gelijk aan '2023' zullen getoond worden. Een overzicht van alle query-mogelijkheden vind je hier: https://www.odata.org/getting-started/basic-tutorial#queryData

GeertBonte commented 3 days ago

Pro-tip: sinds er een API-key ingesteld is op de ODS van PinC, kun je de ODS niet langer zomaar benaderen via een webbrowser. Je krijgt een foutmelding te zien (‘Guest user group not found, No access!’). Bij elke aanroep moet nu immers een API-key opgegeven worden, en dat kan niet zomaar in een browser ...

... tenzij je gebruikmaakt van een browserextensie zoals ‘Modify Header Value (HTTP Headers)’. Deze extensie is zowel voor Microsoft Edge als voor Google Chrome beschikbaar. Met Mozilla Firefox kun je de extensie ‘Modify Header Value’ gebruiken. Eenmaal de extensie geïnstalleerd, voeg je een regel toe voor https://provincies.incijfers.be/jiveservices/odata/, met als header name ‘apikey’ en als header value de API-key die je gekregen hebt.

emdockx commented 2 days ago

Voor wie de ODS op andere manieren wil raadplegen zoals Python of R volstaat het om enkele lijntjes code toe te voegen (zie onderaan). @GeertBonte, vul jij dit eventueel aan in onze handleiding van ODS?

Voor Python:

import requests url = 'https://beta-provincies.incijfers.be/jiveservices/odata/Variables' headers = {'apikey': 'HIER-KOMT-API-KEY'} r = requests.get(url, headers = headers)

Voor R:

_library(httr) library(jsonlite) url = 'https://provincies.incijfers.be/jiveservices/odata/Variables' headers = addheaders(apikey = 'HIER-KOMT-API-KEY') r = GET(url, headers)

GeertBonte commented 2 days ago

De handleiding is aangepast om het gebruik van de API-key toe te lichten. Er worden voorbeelden gegeven met een fictieve key. Het hoofdstuk over Excel heb ik weggelaten, omdat het veel te omslachtig wordt om de ODS met Excel te benaderen als er een API-key meegegeven moet worden. Er kan dan immers geen gebruik meer gemaakt worden van de OData-import omdat je langs die weg geen API-key kunt opgeven. In theorie zou het wel moeten kunnen via 'Gegevens ophalen > Van het web'. Dan kun je wel een key opgeven maar de verdere werkwijze is zo omslachtig dat we dit beter gewoon weglaten.

@emdockx: ik heb ook je voorbeeld in R toegevoegd (waarvoor hartelijk dank).