Migratie PDOK Locatieserver naar het nieuwe PDOK platform afgerond

Toepassingen LocatieServer
#1

De PDOK Locatieserver is gemigreerd naar het nieuwe 3G platform van PDOK. Hiermee blijven we ook in de toekomst een betrouwbare en optimale dienstverlening bieden. Het toevoegen van nieuwe data of functionaliteiten is geen onderdeel geweest van de werkzaamheden.

Wat is er gewijzigd?
Als gevolg van de migratie zijn de API’s beschikbaar via nieuwe URL’s:

Suggest:

https://api.pdok.nl/bzk/locatieserver/search/v3_1/suggest

Lookup:

https://api.pdok.nl/bzk/locatieserver/search/v3_1/lookup

Free:

https://api.pdok.nl/bzk/locatieserver/search/v3_1/free

Reverse Geocoder:

https://api.pdok.nl/bzk/locatieserver/search/v3_1/reverse

De API’s worden gepubliceerd volgens de Open API Specificatie op https://api.pdok.nl/bzk/locatieserver/search/v3_1/ui/. Hiermee zijn de mogelijkheden van de Locatieserver API’s (input en output) gedocumenteerd, waardoor afnemers snel inzicht in de mogelijkheden en resultaten krijgen. Voor PDOK betekent dit een gestandaardiseerde manier van bevragingen, wat de impact van onderhoud aan de PDOK Locatieserver een stuk vermindert.

Afnemers van de Locatieserver wordt met klem gevraagd om binnen 6 maanden over te stappen op de nieuwe URL’s zoals hierboven beschreven. Oude URL’s te beginnen met https://geodata.nationaalgeoregister.nl (verschillende versies) komen op 2 augustus 2023 te vervallen.

De nieuwe API’s bieden geen mogelijkheid meer om naast JSON ook XML als output formaat op te geven. Het aantal bevragingen van XMLten opzichte van JSON was zeer gering en vraagt veel onderhoud.

Ook zijn er twee extra velden geïntroduceerd in de output van de API’s, wat naar verwachting weinig impact tot gevolg heeft.

Heeft u vragen of opmerkingen dan horen we dat graag!

1 like
#2

Klopt bovenstaande url voor de Reverse Geocoder wel? Moet dit niet https://api.pdok.nl/bzk/locatieserver/search/v3_1/reverse zijn?

2 likes
#3

@copierrj bedankt voor je oplettendheid. We hebben het aangepast!

#4

Het lijkt erop alsof een cross-origin verzoek nog niet helemaal goed werkt. Een OPTIONS verzoek op /locatieserver/search/v3_1/suggest geeft een “405 method not allowed” terug, waardoor verzoeken vanaf een andere origin falen. Zouden jullie dit kunnen repareren?

#5

Het valt mij wel op dat bijv. onderstaande twee requests (zonder parameters) een verschillende response geven, dus het lijkt toch iets meer dan alleen een migratie.
https://geodata.nationaalgeoregister.nl/locatieserver/suggest
https://api.pdok.nl/bzk/locatieserver/search/v3_1/suggest

#6

@nicoburgerhart dat klopt inderdaad. De onderliggende software is ge-upgrade naar de laatste versie. Bovendien valideren we door de nieuwe OpenAPI specificaties de requesten stricter. Hierbij is de q parameter verplicht geworden. Naar ons idee is er geen use-case waarbij de q parameter niet nodig is. Mocht die er wel zijn dan horen we dat graag.

#7

@bartjkdp bedankt voor het melden. De Access-Control-Allow-* headers staan goed, maar de OPTIONS request werkt inderdaad niet meer. We gaan hier direct naar kijken.

#8

Bedankt voor deze toelichting.

#9

Ook al is er een vermoeden dat hier geen use-case voor is, dan nog is het interessant als wijzigingen ook ergens (bijvoorbeeld in zo’n topic als dit) gemeld worden. Er wordt bijvoorbeeld ook gemeld dat XML niet meer mogelijk is als output. Anders moeten ontwikkelaars alles opnieuw uitvinden. Heb het al eens meegemaakt met WFS aanroepen die eerst niet strikt waren en later zomaar wel.

Overigens vind ik het jammer dat XML niet meer mogelijk is want mijn software las dat namelijk uit. Nu wil ik de reden niet betwisten waarom deze keuze gemaakt is, hoewel mijn gevoel zegt dat als er al code ligt om dezelfde data naar XML te exporteren, dat dit niet opnieuw gemaakt hoeft te worden bij de overzetting naar een ander platform.

Overigens ben ik een enorme fan van de locatieserver hoor :slight_smile:

2 likes
#10

@bartjkdp de CORS preflight request gaat nu goed. Dit werkt alleen wanneer de request volgens de http specificaties gedaan wordt, dus met een Origin en Access-Control-Allow-Methods header. Zie voorbeeld:

curl -X OPTIONS -H "Origin: http://example.com" -H "Access-Control-Request-Method: GET" -v https://api.pdok.nl/bzk/locatieserver/search/v3_1/suggest
#11

Onlangs heeft PDOK gecommuniceerd dat de Locatieserver naar het nieuwe platform is gemigreerd (met nieuwe URL’s). Daarbij is gemeld dat XML als output niet meer ondersteund wordt.

Op basis van feedback van gebruikers is echter besloten om dit ook in de nieuwe variant van de Locatieserver weer mogelijk te maken. Naar verwachting zal de XML output volgende week weer beschikbaar zijn. Zodra gereed zal PDOK dit communiceren in deze post op het Geoforum.

4 likes
#12

Top Yvette_PDOK !

#13

Wat fijn PDOK! hier zijn wij heel blij mee.

#14

De XML output functionaliteit voor de nieuwe locatieserver is weer beschikbaar. XML output kan worden opgevraagd met de wt=xml parameter, gelijk aan hoe dat voor de huidige locatieserver is ingericht.

1 like
#15

Toch verbaast het me enigszins hoe zo’n besluit (eerst geen XML en dan weer wel) tot stand komt.

Misschien is dit topic niet de meest logische plek en hoeft zo’n discussie ook niet publiek. Toch zou het fijn zijn als zo’n grote wijziging vooraf wat ruimer onderzocht werd, bijvoorbeeld door een poll of via het panel van het PDOK Ontwikkelteam. Of alvast eerder melden, zodat ontwikkelaars zich erop voor kunnen bereiden.

Heb na de eerste melding een dag uitgetrokken om mijn code om te bouwen, was achteraf dus niet nodig geweest. Heb weer wat geleerd van JSON, zullen we maar zeggen. Deze ervaring zal nu wel meespelen waarom ik toch even wilde reageren op dit besluit :slight_smile:

1 like
#16

De verplichte ‘q’ parameter was niet helemaal duidelijk, dank voor de melding.

Wij hebben in onze applicatie een formulier die op dit moment géén gebruik maakt van de q parameter in de /free service. In dit geval is het use-case: formulier met verschillende velden (bv postcode, huisnummer, huisletter etc), waarbij elk veld expliciet in de query wordt toegevoegd met een filter.

Uiteindelijk resulteert dat in het formaat: /free?fq=type:adres&fq=postcode:1122AA&fq=huisnummer:66.

Dit levert goede betrouwbare resultaten op, echter werkt dat niet meer in 3.1.
Is er een mogelijkheid voor deze functionaliteit zonder ‘vrije’ query?

#17

We hebben dit eerlijkheidshalve onderschat. We zagen laag gebruik (o.a. t.o.v. JSON) en omdat er sprake was van nieuwe URL’s (en een half jaar overgangstermijn) leek het een geschikt moment. Excuses en gelukkig dat de investering in JSON niet helemaal voor niks is geweest.

2 likes
#18

We hebben dit intern nog even besproken en voor de /free API is het inderdaad wellicht handig om zonder q parameter te kunnen zoeken. Voor de /suggest laten we hem wel verplicht omdat deze API specifiek voor autocomplete doeleinden bedoeld is. Als de wijziging is doorgevoerd laat ik het weten.

2 likes
#19

De q parameter is niet langer verplicht op het /free endpoint.

1 like
#20

Zojuist even een test gedaan met de oude en nieuwe versie van de free variant.
Oud:
https://geodata.nationaalgeoregister.nl/locatieserver/v3/free?q=2991HC+and+6&wt=xml&rows=999&plaats=&straatNaam=&huisnummer=6&postcode=2991HC&huisletter=&huisnummertoevoeging=
Nieuw:
https://api.pdok.nl/bzk/locatieserver/search/v3_1/free?q=2991HC+and+6&wt=xml&rows=50

Als ik bij de nieuwe API de velden opneem achter &rows krijg ik een foutmelding. Is dat niet meer toegestaan of niet meer nodig? Overigens geeft de oude versie een hogere score dan de nieuwe.

1 like