Documentatie

Alles wat je nodig hebt om de Postcode API te integreren in je applicatie.

Aan de slag

1Vraag een gratis API key aan via het aanvraagformulier
2Gebruik de Sandbox API voor ontwikkeling en testen
3Schakel over naar de Production API voor live gebruik

API Reference

Bekijk de volledige interactieve API documentatie met alle endpoints, parameters en response voorbeelden. De API Reference bevat alles wat je nodig hebt om snel te integreren.

Open API Reference

Implementatie

De API is eenvoudig te implementeren en geoptimaliseerd voor het automatisch invullen van adresgegevens op basis van postcode en huisnummer. Stuur een GET request naar de API met je API key in de header, en ontvang direct straat, plaats, gemeente en provincie terug.

De URL is opgebouwd als: https://api.postcodeapi.nu/v3/lookup/{postcode}/{number}. Verwijder eventuele spaties uit de postcode en gebruik alleen het huisnummer zonder toevoegingen.

Voorbeeld request:

curl -X GET "https://api.postcodeapi.nu/v3/lookup/6545CA/29" \
  -H "X-Api-Key: YOUR_API_KEY"

Voorbeeld response:

{
  "postcode": "6545CA",
  "number": 29,
  "street": "Waldeck Pyrmontsingel",
  "city": "Nijmegen",
  "municipality": "Nijmegen",
  "province": "Gelderland",
  "location": {
    "type": "Point",
    "coordinates": [5.858910, 51.843765]
  }
}

Veelgemaakte fouten

De API werkt niet vanuit de browser

Direct aanroepen vanuit de browser (JavaScript) resulteert in een CORS-fout. Bovendien zou je API key zichtbaar zijn in de broncode. Gebruik daarom altijd een server-side oplossing zoals een serverless function (Vercel, Netlify, AWS Lambda) als tussenlaag.

Geen Request Payload of Content-Type header meesturen

Stuur geen Request Payload of Content-Type header mee in de requests. Het betreft een GET operatie waarbij alle parameters in de URL worden meegegeven, niet in de body.

Sandbox Omgeving

De sandbox is een testomgeving waarmee je de API kunt uitproberen zonder kosten. Ideaal om te ontdekken hoe de API werkt voordat je live gaat. Na implementatie kun je via je account upgraden naar een betaald pakket en overschakelen naar de productie-URL. Ook met een betaalde key kun je de sandbox blijven gebruiken, bijvoorbeeld in een testomgeving.

Sandbox endpoint:

https://sandbox.postcodeapi.nu/v3/lookup/{postcode}/{number}

Let op: alleen onderstaande testcombinaties werken in de sandbox. Voor echte adresgegevens heb je een betaald pakket en de productie-URL nodig.

Postcode	Huisnummer	Resultaat
`6545CA`	`29`	200 OK – Waldeck Pyrmontsingel, Nijmegen, Gelderland
`1021JT`	`19`	200 OK – Hamerstraat, Amsterdam, Noord-Holland
`5038EA`	`17`	200 OK – Stationsstraat, Tilburg, Noord-Brabant
`3030AC`	`100`	200 OK – 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