Referentie

Basis-URL https://woz-api.nl. Alles is GET, alles geeft JSON. De gezaghebbende machineleesbare definitie is de OpenAPI-specificatie; deze pagina is de leesbare versie daarvan.

Authenticatie

Elke call vraagt een sleuteI in een header. Beide vormen werken: X-Api-Key: {key} of Authorization: ApiKey {key}. Sleutels maak je aan op woz-api.nl/ApiKeys.

Zonder sleutel mag je 5 adressen per IP-adres opvragen, daarna volgt een 403.

Endpoints

Endpoint	Parameters	Wat het doet
`GET /Api/Adres`	`adres` (verplicht), `geometrie`	Zoekt op een vrij ingevoerd adres
`GET /Api/Nummeraanduiding/{id}`	`id` (pad), `geometrie`	Zoekt op een BAG-nummeraanduiding
`GET /Api/AdresseerbaarObject/{id}`	`id` (pad), `geometrie`	Zoekt op een verblijfsobject, ligplaats of standplaats
`GET /Api/Credits`	geen	Resterend creditsaldo van de sleutel

geometrie=true voegt de perceelgrenzen als GeoJSON toe, in WGS84. Standaard staat dat uit, omdat het de respons fors groter maakt. Zet het alleen aan als je echt gaat tekenen.

Respons

Alle drie de zoek-endpoints geven dezelfde structuur terug.

Veld	Type	Toelichting
`adres`	string	Het genormaliseerde adres
`bag`	object	BAG-adresgegevens, zie hieronder
`wozObject`	object	WOZ-objectnummer en grondoppervlakte
`woz`	array	De vastgestelde waarden per peildatum
`percelen`	array	Actuele percelen uit de Kadastrale Kaart
`kadastraleObjecten`	array	De aanduiding waar de WOZ-registratie aan hangt

Twee kadastrale velden, en dat is geen fout. percelen is de actuele perceelsituatie uit de open Kadastrale Kaart. kadastraleObjecten is de aanduiding waaraan de WOZ-registratie hangt. Die kunnen verschillen, bijvoorbeeld na een perceelsplitsing. Gebruik percelen voor oppervlakte en kaartwerk, en kadastraleObjecten als je de WOZ-administratie wilt volgen.

`woz`

Veld	Type	Toelichting
`peildatum`	string	Waardepeildatum, doorgaans 1 januari
`vastgesteldeWaarde`	integer	De WOZ-waarde in hele euro's

Sorteer zelf op peildatum als je de meest recente waarde wilt; de volgorde van de reeks is geen contract.

`bag`

Veld	Type
`adresseerbaarobjectId`	string
`nummeraanduidingId`	string
`straatnaam`	string
`huisnummer`	integer
`postcode`	string
`woonplaatsnaam`	string

`wozObject`

Veld	Type	Toelichting
`wozobjectnummer`	integer	Uniek nummer in de LV WOZ
`grondoppervlakte`	integer	In m², indien bekend

`percelen`

Veld	Type	Toelichting
`aanduiding`	string	Bijvoorbeeld `ASD04 F 1145`
`kadastraleGemeenteCode`	string	AKR-code, bijvoorbeeld `ASD04`
`kadastraleGemeente`	string	Naam van de kadastrale gemeente
`kadastraleSectie`	string	Sectieletter
`perceelnummer`	integer	Nummer binnen de sectie
`oppervlakteM2`	integer	Kadastrale grootte in m²
`soortGrootte`	string	Of de grootte exact of geschat is
`perceelId`	string	Identificatie van het perceel
`geometrie`	object	GeoJSON, alleen met `geometrie=true`

Fouten

Elke fout uit de API zelf heeft deze vorm:

Veld	Type	Toelichting
`fout`	string	Korte omschrijving
`code`	string	Machineleesbare code
`status`	integer	De HTTP-status
`detail`	string	Wat er precies misging
`traceId`	string	Vermeld dit bij support

Een 400 door modelvalidatie komt van ASP.NET zelf en heeft de ValidationProblemDetails-vorm met een errors-object. Schrijf je foutafhandeling daarom op de HTTP-status en niet op de aanwezigheid van fout.

Limieten en credits

1 credit is 1 uniek adres. Hetzelfde adres binnen 7 dagen opnieuw opvragen is gratis; de request wordt wel echt uitgevoerd, het is een kortingsregel en geen cache.
Een mislukte lookup kost geen credit.
Zonder account: 5 adressen per IP, daarna 403.
Saldo in de responseheader X-Credits-Remaining, of via GET /Api/Credits.
Bij ongebruikelijke load geldt fair use; vang 429 af met exponentiële backoff.

Prijzen en account

De staffels staan publiek, vanaf EUR 0,35 per uniek adres excl. btw. Een gratis account geeft 10 credits om de integratie af te maken.