Documentatie

De postcode-service.nl API biedt eenvoudige toegang tot alle Nederlandse adressen via de officiële BAG-data van het Kadaster. Stuur een postcode en huisnummer, ontvang een volledig adresobject terug.

Quickstart

Na registratie ontvang je direct een API key. Je eerste request in cURL:

curl -s \
  -H "X-Api-Key: JOUW-API-KEY" \
  "https://api.postcode-service.nl/v3/lookup/1021JT/19"

Authenticatie

Stuur je API key mee als HTTP header:

X-Api-Key: JOUW-API-KEY

Endpoint

Omschrijving	URL
Productie	GET https://api.postcode-service.nl/v3/lookup/{postcode}/{huisnummer}
Sandbox	GET https://sandbox.postcode-service.nl/v3/lookup/{postcode}/{huisnummer}

Parameters:

postcode — Zonder spatie, hoofdletterongevoelig (bv. 1021JT of 1021jt)
huisnummer — Huisnummer met optionele huisletter/toevoeging (bv. 19, 19A, 19-bis)

Response formaat

{
  "postcode": "1021JT",
  "number": 19,
  "street": "Hamerstraat",
  "city": "Amsterdam",
  "municipality": "Amsterdam",
  "province": "Noord-Holland",
  "location": {
    "type": "Point",
    "coordinates": [4.917652, 52.387855]
  }
}

Alle velden zijn altijd aanwezig in de response.

Foutcodes

Code	Omschrijving
`200`	Adres gevonden
`400`	Ongeldig postcode- of huisnummerformaat
`401`	Ongeldige of ontbrekende API key
`404`	Adres niet gevonden
`429`	Rate limit overschreden (per seconde of per maand)

Sandbox

Gebruik je sandbox API key voor ontwikkeling. De sandbox retourneert altijd dezelfde vaste testresponses:

Postcode	Huisnummer	Adres
`1021JT`	19	Hamerstraat, Amsterdam
`2585EM`	79	Lange Voorhout, Den Haag
`3011AD`	1	Coolsingel, Rotterdam
`5611AZ`	1	Nachtegaallaan, Eindhoven
`9726AB`	1	Paterswoldseweg, Groningen

Codevoorbeelden

PHP

<?php
$postcode = '1021JT';
$huisnummer = '19';
$apiKey = 'JOUW-API-KEY';

$response = file_get_contents(
    "https://api.postcode-service.nl/v3/lookup/{$postcode}/{$huisnummer}",
    false,
    stream_context_create(['http' => [
        'header' => "X-Api-Key: {$apiKey}"
    ]])
);

$address = json_decode($response, true);
echo $address['street'] . ', ' . $address['city'];

Node.js

const response = await fetch(
  'https://api.postcode-service.nl/v3/lookup/1021JT/19',
  { headers: { 'X-Api-Key': 'JOUW-API-KEY' } }
);
const address = await response.json();
console.log(`${address.street}, ${address.city}`);

Python

import requests

response = requests.get(
    'https://api.postcode-service.nl/v3/lookup/1021JT/19',
    headers={'X-Api-Key': 'JOUW-API-KEY'}
)
address = response.json()
print(f"{address['street']}, {address['city']}")

Rate limits

Er zijn twee rate limits:

Per seconde — bepaald door je plan (5–25 calls/sec). Bij overschrijding: HTTP 429 met Retry-After: 1.
Per maand — het maandbudget van je plan. Reset op de 1e van de maand. Bij overschrijding: HTTP 429 met upgrade-suggestie.

Response headers:

X-RateLimit-Limit — Maandlimiet
X-RateLimit-Remaining — Resterende calls
X-RateLimit-Reset — Unix timestamp van reset