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 sleutel in een header. Beide vormen werken: X-Api-Key: {key} of Authorization: ApiKey {key}. Sleutels maak je aan op woz-api.nl/ApiKeys.

Zonder account vraag je een gratis proefsleutel aan met POST https://woz-api.nl/Api/Proef: 5 unieke adressen, 10 met het e-mailadres van de gebruiker (POST /Api/Proef/Email). Zonder sleutel geeft de API 401 met code SleutelOntbreekt; een verbruikte proef geeft 402 met code ProefVerbruikt. Een sleutel hoort in een header, nooit in een URL.

Een hele lijst

POST https://woz-api.nl/Api/Lijst met {"adressen": [...]}, elk adres als tekst of als object met straat, huisnummer, huisletter, toevoeging, postcode en plaats. Of een Excel- of CSV-bestand in base64 (bestand en bestandsnaam). Daarna loopt een gratis proef van 5 adressen; GET /Api/Lijst/{token}?wacht=20 wacht tot de status wacht_op_betaling is en geeft de proefrijen, de prijs voor de hele lijst en betaling.betaalUrl, de pagina waar de gebruiker zelf met iDEAL betaalt. Na betaling staan de rijen onder links.resultaten en het bestand onder links.download. Een lijst betaal je per lijst, niet met credits.

AI-assistenten en MCP

Een MCP-server op https://woz-api.nl/Api/Mcp (Streamable HTTP; zonder inloggen, of in Claude en Claude Code met je eigen Wozapi-account via OAuth), met tools voor een proef, een opvraging, een hele lijst en een betaallink. Uitleg voor agents, met de foutcodes en de voorgeschreven reactie: woz-api.nl/voor-ai-agents. De specificatie zelf: https://woz-api.nl/openapi.json.

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.

energielabel=true voegt het geregistreerde energielabel uit EP-Online van RVO toe, in het veld energielabel. Standaard staat dat uit; zonder de parameter ontbreekt het veld. Het kost geen extra credit. Bouwjaar, oppervlakte en gebruiksdoel uit de BAG staan altijd in bag.

subsidietoets=true toetst de woning aan de gemeentelijke regelingen met een WOZ-grens, zoals een isolatiesubsidie, in het veld subsidietoets: de gemeente van het adres, en per regeling of de woning onder de grens valt, op de peildatum die de regeling zelf noemt, met het bouwjaar en (met energielabel=true) het label. Elke gemeente is nagelezen; het overzicht staat op woz-api.nl/woz-grens-isolatiesubsidie. Het kost geen extra credit.

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; leeg als er geen openbare WOZ-waarde is
`huidigeWaarde`	object	De nieuwste waarde uit `woz`, of `null`
`wozStatus`	string	`gevonden`, `geen_woning` of `geen_waarde`, zie hieronder
`percelen`	array	Actuele percelen uit de Kadastrale Kaart
`kadastraleObjecten`	array	De aanduiding waar de WOZ-registratie aan hangt
`energielabel`	object	Alleen met `energielabel=true`, zie hieronder
`subsidietoets`	object	Alleen met `subsidietoets=true`, zie hieronder

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.

`wozStatus`

Waarde	Betekenis
`gevonden`	`woz` heeft een of meer waarden
`geen_woning`	Geen waarde, en volgens de BAG heeft het pand geen woonfunctie (zie `bag.gebruiksdoelen`). Alleen van woningen is de WOZ-waarde openbaar.
`geen_waarde`	Geen waarde, terwijl de BAG een woonfunctie noemt of het gebruiksdoel niet bekend is

Een lege woz is een antwoord, geen storing. Het adres bestaat, er is alleen geen openbare WOZ-waarde, bijvoorbeeld bij een kantoor, kerk of hotel. Je krijgt een 200 met woz: [] en huidigeWaarde: null, en het kost geen credit. Opnieuw proberen verandert niets, ook niet na een pauze van seconden of minuten. Een tijdelijke storing geeft altijd een foutstatus (502 of 503), nooit een 200 met een lege woz.

`bag`

Veld	Type
`adresseerbaarobjectId`	string
`nummeraanduidingId`	string
`straatnaam`	string
`huisnummer`	integer
`postcode`	string
`woonplaatsnaam`	string
`bouwjaar`	integer
`oppervlakte`	integer
`gebruiksdoelen`	array
`pandIds`	array

bouwjaar is het oorspronkelijke bouwjaar van het pand; ligt het verblijfsobject in meer panden, dan het oudste. oppervlakte is de gebruiksoppervlakte in m². Kent de BAG geen verblijfsobject, zoals bij een ligplaats, dan zijn deze velden null.

`energielabel`

Veld	Type	Toelichting
`status`	string	`gevonden`, `geen_label` of `niet_beschikbaar` (probeer het later opnieuw)
`klasse`	string	Van `A++++` tot en met `G`
`registratiedatum`	string	jjjj-mm-dd
`geldigTot`	string	jjjj-mm-dd; ligt die in het verleden, dan is het label verlopen
`gebouwtype`	string	Het woningtype volgens het label
`gebouwsubtype`	string	Bij een appartement de ligging in het gebouw
`vereenvoudigd`	boolean	True bij een vereenvoudigd label, de methode van voor 2021
`primaireFossieleEnergie`	number	kWh per m² per jaar

`subsidietoets`

Veld	Type	Toelichting
`status`	string	`getoetst`, `geen_regeling` (nagelezen, geen regeling met een WOZ-grens) of `niet_beschikbaar` (de gemeente kon nu niet worden bepaald)
`gemeente`	object	`code` (CBS, `GM0363`) en `naam`
`nagelezen`	string	jjjj-mm-dd: wanneer we deze gemeente voor het laatst nalazen
`regelingen[].uitkomst`	string	`onder_grens`, `boven_grens`, `peildatum_ontbreekt`, `geen_waarde`, `geen_harde_grens`, `grens_onbekend` of `buiten_gebied` (een wijkregeling, en het adres ligt erbuiten)
`regelingen[].grenzen`	array	Per grens `euro`, `peildatum`, de `wozWaarde` op die peildatum, `onderGrens` en of hij voor iedereen geldt (`telt`)
`regelingen[].voorwaarden`	array	Wat per adres te toetsen is, zoals bouwjaar en label: `tekst`, `waarde`, `voldoet`
`regelingen[].nogNaTeGaan`	array	Wat per adres niet te weten is, zoals eigenaar en bewoner of een inkomen
`regelingen[].bedragen`	array	Het bedrag per doelgroep: `doelgroep`, `maxEuro`, `percentage` en `voorwaarde` (bijvoorbeeld een inkomensgrens)
`regelingen[].gebied`	array	Alleen bij een wijkregeling: de postcodes waar hij geldt
`regelingen[].gewijzigd`	string	jjjj-mm-dd: de laatste wijziging in grens, bedrag of status, als die is vastgelegd; alle wijzigingen ook als RSS op `https://woz-api.nl/woz-grens-isolatiesubsidie/wijzigingen.xml`
`regelingen[].soort`	string	`open`, `uitnodiging`, `budget_op`, `gesloten`, `vve` of `hoger_bedrag`

`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 of object	Wat er precies misging; soms een object, bijvoorbeeld met een link om op te waarderen
`traceId`	string	Vermeld dit bij support

Dat geldt ook voor een 400 door modelvalidatie; detail bevat dan per veld de meldingen. Match in code op code, niet op de tekst in fout: die tekst kan wijzigen, de codes niet.

Code	Status	Betekenis en wat je doet
`InvalidInput`	400	Parameter ontbreekt of is onbruikbaar, bijvoorbeeld een BAG-id dat geen 16 cijfers heeft. Pas de invoer aan.
`SleutelOntbreekt`	401	Geen sleutel meegestuurd. Vraag een gratis proefsleutel aan met `POST /Api/Proef`, of gebruik de sleutel van je account.
`SleutelVerlopen`	401	De proefsleutel is verlopen of ingetrokken. Vraag een nieuwe aan.
`Unauthorized`	401	De sleutel klopt niet of is ingetrokken.
`ProefVerbruikt`	402	De gratis proef is op. Geef het e-mailadres van de gebruiker (`POST /Api/Proef/Email`) of ga verder met credits; vraag geen nieuwe proefsleutel.
`InsufficientCredits`	402	Het saldo is op. `detail.opwaarderen` geeft de pagina om op te waarderen, `detail.betaalUrl` een betaallink die de gebruiker zelf opent.
`ScopeOntbreekt`	403	Het OAuth-token mist de scope voor deze aanroep; laat de klant opnieuw koppelen.
`ApiCredentialBuitenApi`	403	Een sleutel of token werkt alleen op `/Api`, niet op een webpagina.
`AddressNotFound`	404	Dit adres bestaat niet in de basisregistratie; controleer postcode en huisnummer. Een adres dat wel bestaat maar geen openbare WOZ-waarde heeft, geeft een `200` met een lege `woz`, zie `wozStatus`.
`NotFound`	404	Dit BAG-id is niet gevonden.
`NonResidential`	404	Bij dit adres hoort geen nummeraanduiding, dus ook geen WOZ-object. Zeldzaam: een gewone niet-woning, zoals een kantoor, geeft een `200` met `wozStatus` `geen_woning`.
`PdokSuggestFailed`, `PdokLookupFailed`, `PdokFreeFailed`	502	Het adres opzoeken lukte tijdelijk niet. Opnieuw proberen; kost niets.
`UpstreamUnavailable`	503	De WOZ-gegevens zijn tijdelijk niet beschikbaar. Wacht het aantal seconden uit `Retry-After` (60) en probeer het opnieuw; kost niets.
`TeVeelVerzoeken`, `ProefTijdelijkVol`	429	Te veel verzoeken, of de gratis proeven zijn voor vandaag op. Wacht het aantal seconden uit `Retry-After`.
`ServerError`	500	Onverwachte fout aan onze kant. Vermeld de `traceId` bij een supportvraag.

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 opvraging die op een fout eindigt kost geen credit, en een antwoord zonder WOZ-waarden (een lege woz) ook niet.
Zonder account: een gratis proefsleutel voor 5 unieke adressen via POST /Api/Proef.
Een lijst: hoogstens 250 adressen met een proefsleutel, 10.000 met een account.
Saldo in de responseheader X-Credits-Remaining, of via GET /Api/Credits.
Bij 502 en 503 opnieuw proberen: na het aantal seconden uit Retry-After als die er staat, anders met een oplopende wachttijd, bijvoorbeeld na 1, 5 en 15 seconden. Sla het adres niet over.

Prijzen en account

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