Adreslookup API-contract.

GET /v1/address zoekt Nederlandse adresdata op basis van postcode, huisnummer en optionele toevoeging.

GET https://api-postcode.casag.nl/v1/address
X-API-Key: ${GEOLEDGER_API_KEY}

Doel en authenticatie

De route zoekt exacte genormaliseerde invoer in BAG-gebaseerde adresdata. Authenticatie gebeurt met X-API-Key. De publieke hostname blijft momenteel api-postcode.casag.nl.

Lees de authenticatiehandleiding

Queryparameters
Parameter	Verplicht	Type	Regels
postcode	Ja	string	Nederlandse postcode; spaties worden verwijderd, letters worden hoofdletters
huisnummer	Ja	string	1–5 cijfers; numerieke waarde 1–99999
toevoeging	Nee	string	Maximaal 5 letters/cijfers na normalisatie; spaties verdwijnen

Requestvoorbeeld

curl --get 'https://api-postcode.casag.nl/v1/address' \
  --header "X-API-Key: ${GEOLEDGER_API_KEY}" \
  --data-urlencode 'postcode=1012JS' \
  --data-urlencode 'huisnummer=1'

Voorbeeldinvoer; geen live bevestiging van een adres. De key komt uit je serveromgeving.

Responsevelden
Veld	Type	Betekenis
status	string	ok, not_found of ambiguous
request.postcode	string	Genormaliseerde postcode
request.huisnummer	integer	Genormaliseerd huisnummer
request.toevoeging	string of null	Genormaliseerde toevoeging; null bij lege invoer
address	object of null	Bij ok: straat en woonplaats
candidates	array	Bij ambiguous: verschillende straat-/woonplaatscombinaties

Succesvolle responsevorm

{
  "status": "ok",
  "request": {"postcode": "1012JS", "huisnummer": 1, "toevoeging": null},
  "address": {"straat": "<straat uit dataset>", "woonplaats": "<woonplaats uit dataset>"},
  "candidates": []
}

Schematisch voorbeeld met placeholders voor de adreswaarden; geen live lookup.

Fouten en quota-impact

Geldige lookupinvoer verbruikt quota voordat de dataset wordt geraadpleegd. Dat geldt ook bij not_found en ambiguous. Ongeldige invoer geeft 422 zonder adresquota. Ongeldige authenticatie geeft 401; overschreden quota geeft 429.

Alle fouten en resultaatstatussen Quota en limits Nederlandse invoer en edge cases

Contract gecontroleerd op 30 september 2026 aan de hand van de huidige API-broncode. De actieve accountlimits vind je in Mijn account.