Zoeken naar contactgegevens overheden en politici

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 types de waarde 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 414 gemeenten zijn, terwijl dit er 355 zouden moeten zijn. Dit komt omdat er ook gemeenten in staan zoals Winsum, Noordwijkerhout en Haren 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 355 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 enum ootype is hernoemt naar types van enum array ootype[], zie upgrade instructie

Features:

Opgeloste bugs:

  • beleidsterreinen, resourceidentifiers en wettelijkevoorschriften 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 naar v1 (de v0 API zal niet meer te bereiken zijn)
  • dinsdag 31 maart 2020 23:59:59 GMT: de v0 API zal antwoorden met HTTP Status 410 Gone

Indien er meer formaatswijzigingen komen aan de Overheids Almanak kan het zijn dat het tijdspad wordt ingekort.