Haal Centraal ‘WOZ Bevragen’ API: wat gemeenten krijgen, hoe het technisch werkt, en wat je daarvan kunt leren

De Haal Centraal ‘WOZ Bevragen’ API is geen publieks-API, maar een gestandaardiseerd koppelvlak waarmee overheden WOZ-gegevens uit de landelijke voorziening ontsluiten. In dit artikel leggen we uit wat gemeenten ermee krijgen, hoe het technisch in elkaar zit volgens de Nederlandse API-standaarden, waar de grenzen liggen, en — misschien wel het belangrijkste — wat jij als developer in vastgoed/fintech/proptech daarvan kunt leren voor je eigen dataproducten.

TL;DR

Haal Centraal ‘WOZ Bevragen’ is een overheids-API: bedoeld voor bevoegde afnemers, niet voor publiek of bulkcommercieel gebruik.
De API volgt de NL API Strategie: REST+JSON, duidelijke identificaties (WOZ-objectnummer) en koppelingen naar BAG/BRK.
Je kunt gericht bevragen (bijv. op adres-ID of WOZ-objectnummer), vaak met tijdsdimensie (waardepeildatum/beschikking).
De opzet leert je hoe je WOZ, BAG en BRK semantisch netjes koppelt — cruciaal voor stabiele vastgoed- en riskmodellen.
WozApi levert vergelijkbare consistentie en documentatie, maar dan voor niet-publieke en publieke routes die jij wél mag gebruiken.

Schematische keten: gemeente → LV WOZ/Kadaster → Haal Centraal/overheden → waardeloket/publiek — De WOZ-keten in het kort: gemeenten taxeren; LV WOZ beheert; Haal Centraal standaardiseert het bevragen binnen de overheid; publieksinzage loopt via het WOZ-waardeloket.

Wat is ‘WOZ Bevragen’ binnen Haal Centraal?

Haal Centraal is een VNG Realisatie-programma dat consistente API’s voorschrijft voor basisregistraties en landelijke voorzieningen. ‘WOZ Bevragen’ is het uniform beschreven koppelvlak om WOZ-objecten en bijbehorende waarden uit de landelijke voorziening (LV WOZ, beheerd door het Kadaster) gericht op te vragen door bevoegde overheidsorganisaties.

Belangrijk: dit is níet hetzelfde als het WOZ-waardeloket voor burgers/bedrijven. Het waardeloket toont beperkt openbare waarden (met privacyfilters) en geen volledige object-/historiedetails. De Haal Centraal-API is voor overheden met een taak, onder strikte autorisatie en voorwaarden.

Samengevat: ‘openbaar’ is niet ‘open’. De Wet WOZ kent openbaarheid voor bepaalde gegevens (o.a. openbare woningwaarden), maar machine-to-machine toegang tot volledige datasets is voorbehouden aan bevoegde partijen onder contractuele en wettelijke afspraken.

Wat krijgen gemeenten via de ‘WOZ Bevragen’ API?

De kern van de API is het WOZ-object met een stabiele identificatie (het WOZ-objectnummer). Daaromheen zijn relaties en eigenschappen beschikbaar die het object in context plaatsen:

Kernentiteiten en relaties

WOZ-object (identificatie: wozObjectNummer)
Adres-koppelingen via BAG-identificaties:
- nummeraanduidingIdentificatie (adres-ID)
- verblijfsobjectIdentificatie en/of pandIdentificatie (waar relevant)
Kadastrale koppeling (BRK):
- kadastraleAanduiding of een lijst van kadastraalOnroerendeZaken die aan het WOZ-object zijn gerelateerd
Objectkenmerken (bijv. objecttype zoals woning/niet-woning, deelobjecten waar van toepassing)
Waarden:
- vastgesteldeWaarde per waardepeildatum/beschikkingsjaar
- statussen (bijv. vastgesteld), ingangs-/einddatums en eventuele correcties

Gemeenten kunnen hiermee gericht verifiëren, mutaties verwerken en hun eigen processen (heffing, bezwaar/beroep, kwaliteitscontrole) ondersteunen. Historie en geldigheid zijn doorgaans onderdeel van het model, zodat je een bepaald object voor een specifieke peildatum kunt reproduceren.

Geen vrije bulkdump, wel gerichte bevraging

De API is ontworpen voor bevragen, niet voor het massaal kopiëren van volledige datasets. Verwacht dus:

Zoek- en filterparameters (bijv. op wozObjectNummer, nummeraanduidingIdentificatie, kadastrale aanduiding)
Beperkingen en autorisatie die passen bij je taak en gebied
Rate limiting en logging/audit op de aansluiting

Relatiemodel: WOZ-object met links naar BAG-adressen en BRK-percelen — Conceptueel gegevensmodel: het WOZ-object vormt de spil; BAG en BRK leveren referenties en geometrische/kadastrale context.

Hoe werkt het technisch? (op hoofdlijnen)

Haal Centraal-API’s volgen de Nederlandse API Strategie (NL GOV). Voor ‘WOZ Bevragen’ betekent dat in de praktijk:

Protocol en formaten

RESTful endpoints met JSON-responses
Heldere resourcepaden, bijvoorbeeld:
- /wozobjecten
- /wozobjecten/{wozObjectNummer}
- relaties of subresources voor waarden en gekoppelde identificaties
Standaard HTTP-statuscodes en foutafhandeling met duidelijke foutobjecten

Autorisatie en toegang

Toegang is voor bevoegde (overheids)afnemers en verloopt via de partij die de API host (bijv. Kadaster/LV WOZ of een door VNG aangewezen voorziening).
Authenticatie/autorisatie verloopt doorgaans via OAuth 2.0 (client credentials) en/of overheidskoppelvlakken (bijv. Digikoppeling/NLx), afhankelijk van de implementatie.
Scopes/rollen bepalen welke gegevens en in welke omvang je mag bevragen.

Filtering, paginering en versiebeheer

Filtering op identificaties (wozObjectNummer, nummeraanduidingIdentificatie) en waar relevant op tijd (bijv. peildatum/waardepeildatum of geldigheid).
Paginering met parameters zoals page en pageSize of limit en offset (raadpleeg de actuele specificatie; dit kan per implementatie afwijken).
Versiebeheer via versie in het pad (v1) of via headers; breaking changes leiden tot nieuwe versies met behoud van backward compatibility waar mogelijk.

Semantische koppelingen

De kracht van Haal Centraal zit in consistente identificaties:

WOZ-objecten