API
De databron wie wij gebruiken is Overheidsorganisaties XML, deze XML converteren en importeren wij in een database die we met een REST API toegankelijk stellen (m.b.v. PostREST met CORS). De API kan zowel JSON als CSV terug sturen. Let op, met PostgREST zijn database intensieve queries te maken, daarom hebben we de query limiet op tien seconden gezet, mocht je hier tegenaan lopen, neem dan vooral contact met ons op dan gaan we een oplossing maken (bijv. een speciale view / API endpoint of uitzondering).
De API heeft vele endpoints maar de overheidsorganisatie
is de interessante, gezien alle objecten een overheidsorganisatie
-object zijn, de andere endpoints zijn voor de onderlinge relaties, maar deze kunnen ook via PostgREST resource embedding tot op zekere hoogte worden meegenomen in de overheidsorganisatie
-call.
Zie onderaan deze pagina de changelog en upgrade instructie vanaf v0
. Voor meer informatie over het tijdspad van versie upgrades van de API zie de deprecation policy, indien mogelijk gebruik dan een HTTP User-Agent met contactgegevens, bijv. User-Agent: Mozilla/5.0 (compatible; ApplicatieNaam/1.0; +https://link-naar-je-applicatie/)
.
Voorbeelden
Gemeente
Het makkelijkste is om de API uit te leggen op basis van voorbeelden. Stel je wilt gegevens hebben van gemeente Amsterdam, dan kan je hier zo naar zoeken:
/overheidsorganisatie?naam=eq.Gemeente Amsterdam
Waarbij eq
staat voor equal
(gelijk), er is een hele lijst met filter operaties.
Stel je wilt nu een lijst met alle gemeenten, dan kan je alle organisaties die in Gemeente
bevatten selecteren:
/overheidsorganisatie?types=cs.{Gemeente}
Waarbij cs
staat voor contains
(bevat), en de {}
een lijst (array) notatie is, in dit geval van slechts één element, een lijst kan meerdere gescheiden worden met een komma (,
).
Als je in de JSON output enkel de afkorting
(de gemeentenaam zonder "Gemeente " ervoor), ictucode
(een code die voor gemeenten gelijk is aan de CBS codering voor gemeenten, met een extra voorloop nul):
/overheidsorganisatie?types=cs.{Gemeente}&select=afkorting,ictucode
Zie ook meer documentatie over het filteren van velden. Zo kunnen we het veld afkorting
hernoemen naar gemeente door gemeente:afkorting
en van het veld ictucode
omzetten in een getal (welke geen voorloopnullen heeft) met ictucode::int
:
/overheidsorganisatie?types=cs.{Gemeente}&select=gemeente:afkorting,ictucode::int
Als je nu oplet zie je dat er 419 gemeenten zijn, terwijl dit er 342 zouden moeten zijn. Dit komt omdat er ook gemeenten in staan zoals Heerhugowaard, Haaren en Appingedam welke allen reeds zijn opgeheven. Dit is te zien aan het einddatum
veld, voor huidige gemeente moet dit veld niet zijn gevuld, ofwel op null
staan:
/overheidsorganisatie?types=cs.{Gemeente}&select=gemeente:afkorting,ictucode::int&einddatum=is.null
Dit is wel een lijst van 342 gemeenten. Misschien wil je de lijst nu nog sorteren, dit kan met order=veldnaam
dus:
/overheidsorganisatie?types=cs.{Gemeente}&select=gemeente:afkorting,ictucode::int&einddatum=is.null&order=afkorting
Vervolgens zouden we nog wat contactinformatie kunnen toevoegen bijv. telefoonnummer(s) en internetpagina(s) maar niet de (post)adressen:
/overheidsorganisatie?types=cs.{Gemeente}&einddatum=is.null&order=afkorting&select=gemeente:afkorting,ictucode::int,contact->telefoon,contact->internet
Het contact
-veld is een JSON veld met een flexibele structuur, zo is het internet en telefoon veld optioneel, en kan het een enkele waarde bevatten of een lijst (array), een waarde kan zowel een simpele tekst bestaan als een {"label": "..", "value": ".."}
-object.
Verkiezing
Ook hebben we de recente kandidatenlijsten en uitslagen van de Kiesraad ingeladen:
/verkiezing
Voor het voorbeeld kunnen we het beste even een filter maken en één verkiezing & gemeente bekijken, bijv. Lingewaard welke voor de gemeenteraadsverkiezingen van 2018 dan de code GR2018_Lingewaard
heeft.
/verkiezing?code=eq.GR2018_Lingewaard
Met de API kunnen we ook in één bevraging gerelateerde data opvragen, zoals bijv. de kieslijsten:
/verkiezing?code=eq.GR2018_Lingewaard&select=*,kieslijst(*)
Waar we vervolgens ook de kandidatlijsten aan kunnen koppelen:
/verkiezing?code=eq.GR2018_Lingewaard&select=naam,verkiezingsdatum,zetels,kieslijst(lijstnummer,naam,verkozenzetels,kandidaat(kandidaatnummer,voornaam,tussenvoegsel,achternaam,voorkeurstemmen))
Changelog
v1.1
Onder de Kiesraad groep zijn bij verkiezing
de volgende velden toegevoegd: voorkeurdrempel
(in procenten van kiesdeler = ceil(geldigeStemmen / zetels)
), opgeroepen
, geldigeStemmen
, blanco
en ongeldig
. Bij kandidaat
zijn deze toegevoegd: verkozen
(true
of NULL
), verkozenpositie
en voorkeurdrempel
(true
: voorkeurstemmen ≥ verkiezing.voorkeurdrempel × kiesdeler / 100
, false
: verkozen door lijst of NULL
: niet verkozen). De positie kan veranderen als iemand lager op de lijst de voorkeurdrempel
heeft behaald, zie ook de uitleg van de Kiesraad over de voorkeurdrempel. De velden zijn niet toegevoegd aan v0
.
v1
Door de Overheids Almanak wijzigingen in 2.4.10 "meerdere organisatietypes mogelijk per organisatie" moest ook de Allmanak API een nieuwe versie krijgen.
type
van enumootype
is hernoemt naartypes
van enum arrayootype[]
, zie upgrade instructie
Features:
- Upgrade van PostgREST 5.2.0 naar 6.0.0 met onze eigen enum array support, de enum array syntax kan mogelijk afwijken van de OpenAPI standaard, zie issue #1353
Opgeloste bugs:
beleidsterreinen
,resourceidentifiers
enwettelijkevoorschriften
zitten niet meer in een dubbele array, maar een enkele
Deprecation Policy
De API zal door dataformaat aanpassingen van de Overheids Almanak soms een update krijgen, brekende updates zullen een nieuwe versie krijgen. Als een oud API endpoint deprecated is, zal de Deprecation
header worden toegevoegd (tesamen met een Sunset
en successor-version link). Indien mogelijk houden we na een upgrade de oude API nog 6 maanden online met deze headers. Na deze 6 maanden zullen we de HTTP status code wijzigen naar 207 Multi-Status
en na een maand naar 301 Moved Permanently
welke we naar de nieuwe API zullen redirecten, waarna we na enige tijd de oude API 410 Gone
zullen laten retourneren.
Vervallen v0
v0
kan nog worden gebruikt, maar deze pakt enkel het eerste type uit de array, wat kan leiden tot onvolledige resultaten.
Upgrades naar v1
: waar eerder type=eq.Gemeente
werd gebruikt kan nu types=cs.{Gemeente}
worden gebruikt.
Tijdspad:
- vrijdag 31 januari 2020 23:59:59 GMT: de HTTP Status zal op
207 Multi-Status
worden gezet (buiten de HTTP status zal de API blijven functioneren) - vrijdag 28 februari 2020 23:59:59 GMT: de API verwijst d.m.v. HTTP Status
301 Moved Permanently
naarv1
(dev0
API zal niet meer te bereiken zijn) - dinsdag 31 maart 2020 23:59:59 GMT: de
v0
API zal antwoorden met HTTP Status410 Gone
Indien er meer formaatswijzigingen komen aan de Overheids Almanak kan het zijn dat het tijdspad wordt ingekort.