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.

PostcodeNumberTestcase
6545CA29200 OK, address found: Waldeck Pyrmontsingel, Nijmegen, Gelderland
1021JT19200 OK, address found: Hamerstraat, Amsterdam, Noord-Holland
5038EA17200 OK, address found: Stationsstraat, Tilburg, Noord-Brabant
3030AC100200 OK, address found: Postbus, Leusden, Utrecht
6545CA29a400 Bad request, invalid number format
6545C29400 Bad request, invalid postcode format
6545C29a400 Bad request, invalid postcode and number format
6545CA299404 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:
Run in 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.