API Documentatie
Integreer postcodedata rechtstreeks in uw applicatie via de PostcodeRegister REST API. Alle responses zijn in JSON-formaat.
Response Formaat
Alle endpoints retourneren hetzelfde envelope-formaat:
// Succes
{
"ok": true,
"data": [ ... ],
"count": 42,
"meta": {
"usage": { "used": 5, "limit": 100, "period": "2026-03" }
}
}
// Fout
{
"ok": false,
"error": {
"code": "INVALID_POSTCODE",
"message": "Postcode must be 4 digits followed by 2 uppercase letters"
}
}Quick Start
- 1
Maak een account aan en genereer een API key
Ga naar Dashboard→ API Keys en klik op “Aanmaken”.
- 2
Stuur de key mee als header
Voeg
X-API-Key: pcr_live_jouw_keytoe aan elk verzoek. - 3
Doe je eerste verzoek
curl -H "X-API-Key: pcr_live_jouw_key" \
"https://postcoderegister.nl/api/v1/lookup/1011AB"Authenticatie
Elk verzoek moet de API key meesturen via de X-API-Key header. Keys zijn gebonden aan je account en kunnen op elk moment worden ingetrokken via het dashboard.
X-API-Key: pcr_live_a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5Endpoints
Error Codes
Bij een fout retourneert de API een JSON-object met ok: false en een error object met code en message:
{
"ok": false,
"error": {
"code": "MISSING_API_KEY",
"message": "X-API-Key header required"
}
}| Code | HTTP | Beschrijving |
|---|---|---|
| MISSING_API_KEY | 401 | Geen X-API-Key header meegegeven |
| INVALID_API_KEY | 401 | Key niet gevonden of ingetrokken |
| QUOTA_EXCEEDED | 402 | Gratis limiet bereikt (100/maand). Abonnement vereist. |
| RATE_LIMITED | 429 | Meer dan 60 verzoeken per minuut |
| INVALID_QUERY | 400 | Zoekterm ontbreekt, te kort, of ongeldig |
| INVALID_POSTCODE | 400 | Postcodeformaat ongeldig (verwacht: 1234AB) |
| INVALID_COORDINATES | 400 | Coördinaten of straal buiten bereik |
| BATCH_TOO_LARGE | 400 | Meer dan 100 postcodes in batch verzoek |
| INTERNAL_ERROR | 500 | Onverwachte serverfout |
Limieten & Prijzen
Batch verzoeken tellen als 1 API request, ongeacht het aantal postcodes (max 100 per batch). Elke response bevat je huidige verbruik in het meta.usage veld.
Code Voorbeelden
JavaScript (fetch)
const API_KEY = "pcr_live_jouw_key";
const BASE = "https://postcoderegister.nl/api/v1";
// Postcode opzoeken
const res = await fetch(`${BASE}/lookup/1011AB`, {
headers: { "X-API-Key": API_KEY },
});
const { ok, data, meta } = await res.json();
if (ok) {
console.log(data.straatnaam, data.plaatsnaam);
console.log(`Verbruik: ${meta.usage.used}/${meta.usage.limit}`);
}
// Batch opzoeken
const batchRes = await fetch(`${BASE}/batch`, {
method: "POST",
headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ postcodes: ["1011AB", "1012AA", "3011AA"] }),
});
const batch = await batchRes.json();
if (batch.ok) {
for (const [code, info] of Object.entries(batch.data)) {
console.log(code, info ? info.straatnaam : "niet gevonden");
}
}Python (requests)
import requests
API_KEY = "pcr_live_jouw_key"
BASE = "https://postcoderegister.nl/api/v1"
HEADERS = {"X-API-Key": API_KEY}
# Postcode opzoeken
r = requests.get(f"{BASE}/lookup/1011AB", headers=HEADERS)
data = r.json()
if data["ok"]:
print(data["data"]["straatnaam"], data["data"]["plaatsnaam"])
print(f"Verbruik: {data['meta']['usage']['used']}/{data['meta']['usage']['limit']}")
# Radius zoeken
r = requests.get(f"{BASE}/radius", headers=HEADERS, params={
"lat": 52.3676, "lng": 4.9041, "radius": 5
})
data = r.json()
if data["ok"]:
print(f"{data['count']} postcodes gevonden")
# Batch opzoeken
r = requests.post(f"{BASE}/batch", headers=HEADERS, json={
"postcodes": ["1011AB", "1012AA", "3011AA"]
})
data = r.json()
if data["ok"]:
for code, info in data["data"].items():
print(code, info["straatnaam"] if info else "niet gevonden")cURL
# Postcode opzoeken
curl -H "X-API-Key: pcr_live_jouw_key" \
"https://postcoderegister.nl/api/v1/lookup/1011AB"
# Zoeken op plaatsnaam
curl -H "X-API-Key: pcr_live_jouw_key" \
"https://postcoderegister.nl/api/v1/search?q=Utrecht"
# Radius zoeken (5 km)
curl -H "X-API-Key: pcr_live_jouw_key" \
"https://postcoderegister.nl/api/v1/radius?lat=52.3676&lng=4.9041&radius=5"
# Alle 6PP in een 4PP gebied
curl -H "X-API-Key: pcr_live_jouw_key" \
"https://postcoderegister.nl/api/v1/area/1011"
# Autocomplete
curl -H "X-API-Key: pcr_live_jouw_key" \
"https://postcoderegister.nl/api/v1/suggest?q=Rott"
# Batch opzoeken
curl -X POST \
-H "X-API-Key: pcr_live_jouw_key" \
-H "Content-Type: application/json" \
-d '{"postcodes":["1011AB","1012AA","3011AA"]}' \
"https://postcoderegister.nl/api/v1/batch"