Documentatie
Op deze pagina vind je informatie over de volgende zaken:
Sandbox
Postcode API v3 kent een zogenaamde 'sandbox' omgeving om test calls te maken. Je kunt deze omgeving gebruiken om te checken hoe de API werkt. Zodra je de sandbox geïmplementeerd hebt kun je je sandbox key via je account upgraden naar een betaalde key en calls naar de productie omgeving maken door de URL aan te passen. Met een betaalde key kun je overigens nog steeds gebruik maken van de sandbox, bijvoorbeeld in een testomgeving.
De lookup
functie van de sandbox is beschikbaar op: https://sandbox.postcodeapi.nu/v3/lookup
. Met onderstaande 'fake' postcode/huisnummer combinaties kun je de sandbox testen.
Let op: alléén onderstaande postcode/huisnummer combinaties werken in de sandbox. Om echte adresgegevens terug te krijgen dien je de productie omgeving te gebruiken. Deze werkt alleen met een betaald pakket.
Postcode | Number | Testcase |
---|---|---|
6545CA | 29 | 200 OK, address found: Waldeck Pyrmontsingel, Nijmegen, Gelderland |
1021JT | 19 | 200 OK, address found: Hamerstraat, Amsterdam, Noord-Holland |
5038EA | 17 | 200 OK, address found: Stationsstraat, Tilburg, Noord-Brabant |
3030AC | 100 | 200 OK, address found: Postbus, Leusden, Utrecht |
6545CA | 29a | 400 Bad request, invalid number format |
6545C | 29 | 400 Bad request, invalid postcode format |
6545C | 29a | 400 Bad request, invalid postcode and number format |
6545CA | 299 | 404 Not found, address not found |
Implementatie
Postcode API v3 is erg eenvoudig te implementeren en geoptimaliseerd om op basis van van postcode en huisnummer een straat en plaats automatisch in te vullen in een formulier. In deze wetenschap is de API dan ook zo simpel mogelijk gehouden. Kort gezegd doe je een GET
request naar de URL van de API, je vergezelt deze request met je API key, en de API geeft een JSON object met straats, plaats, gemeente en provincie terug.
Voorbeeld
Stel, een gebruiker vult de volgende postcode/huisnummer combinatie in:
- Postcode: 6545CA
- Huisnummer: 29
De lookup
functie van de API is beschikbaar op de volgende URL: https://api.postcodeapi.nu/v3/lookup
. Om hier postcode en huisnummer aan toe te voegen, plak je deze er als paden achteraan. Je krijgt dan, in dit geval: https://api.postcodeapi.nu/v3/lookup/6545CA/29
.
Let op: vergeet niet eventuele spaties uit de postcode en letters uit het nummer te halen!
In dit voorbeeld is de API key waarmee we de request willen maken de volgende: 3a696aafc86c408d936d
. Deze stuur je mee met de header X-Api-Key
. De HTTP request die naar de API gemaakt moet worden ziet er dan als volgt uit:
GET https://api.postcodeapi.nu/v3/lookup/6545CA/29 HTTP/1.1
X-Api-Key: 3a696aafc86c408d936d
Of bijvoorbeeld met CURL:
curl -H "X-Api-Key: 3a696aafc86c408d936d" "https://api.postcodeapi.nu/v3/lookup/6545CA/29"
Let op: stuur geen Request Payload
of Content-Type
header mee in de requests, het betreft een GET
operatie!
De API geeft vervolgens de volgende response terug:
HTTP/1.1 200 OK
Content-Type: application/json
{
"postcode": "6545CA",
"number": 29,
"street": "Binderskampweg",
"city": "Nijmegen",
"municipality": "Nijmegen",
"province": "Gelderland",
"location": {
"type": "Point",
"coordinates": [
5.858910083770752,
51.84376540294041
]
}
}
Als je een eigen API key hebt kun je de bovenstaande API call eenvoudig testen met Postman:
Let op: vergeet niet de API key aan te passen!
API reference
De gedetailleerde technische documentatie van de API vind je in de API reference. Hierin zijn alle functies, requests en responses van de API (in het Engels) beschreven. Mocht je de bijbehorende OpenAPI Specification (voorheen Swagger) willen gebruiken om bijvoorbeeld code te genereren, dan kun je deze via de API reference downloaden.
Vorige versie (v2)
Deze documentatie gaat over Postcode API v3. De documentatie van de vorige versie (v2) vind je hier. De nieuwste versie (v3) zal uitgebreid worden met features uit v2 op basis van feedback van onze gebruikers. Pas als we de gewenste usecases ondersteunen in v3 zullen we starten met de uitfasering van v2. Dit is voorlopig nog niet aan de orde en zal uiteraard in nauw overleg met onze gebruikers plaatsvinden.