reference.html

<!doctype html>
<html lang="nl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>WOZ API referentie: endpoints, velden en foutcodes</title>
<meta name="description" content="Volledige referentie van de WOZ API: de vier endpoints, alle responsevelden met hun type, de foutvorm, limieten en de creditregels.">
<link rel="canonical" href="https://wozapi.github.io/reference.html">
<link rel="stylesheet" href="/assets/docs.css">
<!-- Favicons: iconpack van 1 sep 2026, gelijk aan woz-api.nl. Zelfde merk, zelfde tabicoon. -->
<link rel="icon" href="/favicon.ico" sizes="any">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="48x48" href="/favicon-48x48.png">
<link rel="icon" type="image/png" sizes="96x96" href="/favicon-96x96.png">
<link rel="icon" type="image/svg+xml" href="/favicon.svg">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="mask-icon" href="/safari-pinned-tab.svg" color="#E8590C">
<meta name="theme-color" content="#0E1420">
<meta property="og:type" content="article">
<meta property="og:title" content="WOZ API referentie">
<meta property="og:description" content="De vier endpoints, alle responsevelden met hun type, de foutvorm en de limieten.">
<meta property="og:url" content="https://wozapi.github.io/reference.html">
<script type="application/ld+json">
{"@context":"https://schema.org","@type":"TechArticle","headline":"WOZ API referentie: endpoints, velden en foutcodes","description":"Volledige referentie van de WOZ API: endpoints, responsevelden, foutvorm, limieten en creditregels.","url":"https://wozapi.github.io/reference.html","inLanguage":"nl-NL","proficiencyLevel":"Expert","author":{"@type":"Organization","name":"WozApi","url":"https://woz-api.nl"},"about":{"@type":"WebAPI","name":"WOZ API","documentation":"https://wozapi.github.io/reference.html","provider":{"@type":"Organization","name":"WozApi","url":"https://woz-api.nl"}}}
</script>
</head>
<body>
<header class="top">
  <div class="wrap">
    <a class="brand" href="/">wozapi<span aria-hidden="true">/</span>docs</a>
    <nav aria-label="Documentatie">
      <a href="/">Overzicht</a>
      <a href="/getting-started.html">Aan de slag</a>
      <a href="/reference.html" aria-current="page">Referentie</a>
      <a href="/oauth.html">OAuth</a>
      <a href="/clients.html">Clients</a>
      <a href="https://woz-api.nl/swagger">Live testen</a>
      <a href="https://woz-api.nl">woz-api.nl</a>
    </nav>
  </div>
</header>

<main>
<div class="wrap">

<h1>Referentie</h1>
<p class="lead">Basis-URL <code>https://woz-api.nl</code>. Alles is GET, alles geeft JSON.
De gezaghebbende machineleesbare definitie is de
<a href="https://woz-api.nl/swagger">OpenAPI-specificatie</a>; deze pagina is de leesbare versie
daarvan.</p>

<h2>Authenticatie</h2>
<p>Elke call vraagt een sleutel in een header. Beide vormen werken:
<code>X-Api-Key: {key}</code> of <code>Authorization: ApiKey {key}</code>. Sleutels maak je aan
op <a href="https://woz-api.nl/ApiKeys">woz-api.nl/ApiKeys</a>.</p>
<p>Zonder account vraag je een gratis proefsleutel aan met <code>POST https://woz-api.nl/Api/Proef</code>:
5 unieke adressen, 10 met het e-mailadres van de gebruiker (<code>POST /Api/Proef/Email</code>). Zonder
sleutel geeft de API 401 met code <code>SleutelOntbreekt</code>; een verbruikte proef geeft 402 met code
<code>ProefVerbruikt</code>. Een sleutel hoort in een header, nooit in een URL.</p>

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

<h2 id="agents">AI-assistenten en MCP</h2>
<p>Een MCP-server op <code>https://woz-api.nl/Api/Mcp</code> (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: <a href="https://woz-api.nl/voor-ai-agents" rel="nofollow">woz-api.nl/voor-ai-agents</a>.
De specificatie zelf: <code>https://woz-api.nl/openapi.json</code>.</p>

<h2>Endpoints</h2>
<div class="table-scroll">
<table>
  <thead><tr><th>Endpoint</th><th>Parameters</th><th>Wat het doet</th></tr></thead>
  <tbody>
    <tr>
      <td><code>GET /Api/Adres</code></td>
      <td><code>adres</code> (verplicht), <code>geometrie</code></td>
      <td>Zoekt op een vrij ingevoerd adres</td>
    </tr>
    <tr>
      <td><code>GET /Api/Nummeraanduiding/{id}</code></td>
      <td><code>id</code> (pad), <code>geometrie</code></td>
      <td>Zoekt op een BAG-nummeraanduiding</td>
    </tr>
    <tr>
      <td><code>GET /Api/AdresseerbaarObject/{id}</code></td>
      <td><code>id</code> (pad), <code>geometrie</code></td>
      <td>Zoekt op een verblijfsobject, ligplaats of standplaats</td>
    </tr>
    <tr>
      <td><code>GET /Api/Credits</code></td>
      <td>geen</td>
      <td>Resterend creditsaldo van de sleutel</td>
    </tr>
  </tbody>
</table>
</div>

<p><code>geometrie=true</code> 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.</p>

<p><code>energielabel=true</code> voegt het geregistreerde energielabel uit EP-Online van RVO toe, in
het veld <code>energielabel</code>. 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
<code>bag</code>.</p>

<h2>Respons</h2>
<p>Alle drie de zoek-endpoints geven dezelfde structuur terug.</p>

<div class="table-scroll">
<table>
  <thead><tr><th>Veld</th><th>Type</th><th>Toelichting</th></tr></thead>
  <tbody>
    <tr><td><code>adres</code></td><td>string</td><td>Het genormaliseerde adres</td></tr>
    <tr><td><code>bag</code></td><td>object</td><td>BAG-adresgegevens, zie hieronder</td></tr>
    <tr><td><code>wozObject</code></td><td>object</td><td>WOZ-objectnummer en grondoppervlakte</td></tr>
    <tr><td><code>woz</code></td><td>array</td><td>De vastgestelde waarden per peildatum</td></tr>
    <tr><td><code>percelen</code></td><td>array</td><td>Actuele percelen uit de Kadastrale Kaart</td></tr>
    <tr><td><code>kadastraleObjecten</code></td><td>array</td><td>De aanduiding waar de WOZ-registratie aan hangt</td></tr>
    <tr><td><code>energielabel</code></td><td>object</td><td>Alleen met <code>energielabel=true</code>, zie hieronder</td></tr>
  </tbody>
</table>
</div>

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

<h3><code>woz</code></h3>
<div class="table-scroll">
<table>
  <thead><tr><th>Veld</th><th>Type</th><th>Toelichting</th></tr></thead>
  <tbody>
    <tr><td><code>peildatum</code></td><td>string</td><td>Waardepeildatum, doorgaans 1 januari</td></tr>
    <tr><td><code>vastgesteldeWaarde</code></td><td>integer</td><td>De WOZ-waarde in hele euro's</td></tr>
  </tbody>
</table>
</div>
<p>Sorteer zelf op <code>peildatum</code> als je de meest recente waarde wilt; de volgorde van de
reeks is geen contract.</p>

<h3><code>bag</code></h3>
<div class="table-scroll">
<table>
  <thead><tr><th>Veld</th><th>Type</th></tr></thead>
  <tbody>
    <tr><td><code>adresseerbaarobjectId</code></td><td>string</td></tr>
    <tr><td><code>nummeraanduidingId</code></td><td>string</td></tr>
    <tr><td><code>straatnaam</code></td><td>string</td></tr>
    <tr><td><code>huisnummer</code></td><td>integer</td></tr>
    <tr><td><code>postcode</code></td><td>string</td></tr>
    <tr><td><code>woonplaatsnaam</code></td><td>string</td></tr>
    <tr><td><code>bouwjaar</code></td><td>integer</td></tr>
    <tr><td><code>oppervlakte</code></td><td>integer</td></tr>
    <tr><td><code>gebruiksdoelen</code></td><td>array</td></tr>
    <tr><td><code>pandIds</code></td><td>array</td></tr>
  </tbody>
</table>
</div>

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

<h3><code>energielabel</code></h3>
<div class="table-scroll">
<table>
  <thead><tr><th>Veld</th><th>Type</th><th>Toelichting</th></tr></thead>
  <tbody>
    <tr><td><code>status</code></td><td>string</td><td><code>gevonden</code>, <code>geen_label</code> of <code>niet_beschikbaar</code> (probeer het later opnieuw)</td></tr>
    <tr><td><code>klasse</code></td><td>string</td><td>Van <code>A++++</code> tot en met <code>G</code></td></tr>
    <tr><td><code>registratiedatum</code></td><td>string</td><td>jjjj-mm-dd</td></tr>
    <tr><td><code>geldigTot</code></td><td>string</td><td>jjjj-mm-dd; ligt die in het verleden, dan is het label verlopen</td></tr>
    <tr><td><code>gebouwtype</code></td><td>string</td><td>Het woningtype volgens het label</td></tr>
    <tr><td><code>gebouwsubtype</code></td><td>string</td><td>Bij een appartement de ligging in het gebouw</td></tr>
    <tr><td><code>vereenvoudigd</code></td><td>boolean</td><td>True bij een vereenvoudigd label, de methode van voor 2021</td></tr>
    <tr><td><code>primaireFossieleEnergie</code></td><td>number</td><td>kWh per m² per jaar</td></tr>
  </tbody>
</table>
</div>

<h3><code>wozObject</code></h3>
<div class="table-scroll">
<table>
  <thead><tr><th>Veld</th><th>Type</th><th>Toelichting</th></tr></thead>
  <tbody>
    <tr><td><code>wozobjectnummer</code></td><td>integer</td><td>Uniek nummer in de LV WOZ</td></tr>
    <tr><td><code>grondoppervlakte</code></td><td>integer</td><td>In m², indien bekend</td></tr>
  </tbody>
</table>
</div>

<h3><code>percelen</code></h3>
<div class="table-scroll">
<table>
  <thead><tr><th>Veld</th><th>Type</th><th>Toelichting</th></tr></thead>
  <tbody>
    <tr><td><code>aanduiding</code></td><td>string</td><td>Bijvoorbeeld <code>ASD04 F 1145</code></td></tr>
    <tr><td><code>kadastraleGemeenteCode</code></td><td>string</td><td>AKR-code, bijvoorbeeld <code>ASD04</code></td></tr>
    <tr><td><code>kadastraleGemeente</code></td><td>string</td><td>Naam van de kadastrale gemeente</td></tr>
    <tr><td><code>kadastraleSectie</code></td><td>string</td><td>Sectieletter</td></tr>
    <tr><td><code>perceelnummer</code></td><td>integer</td><td>Nummer binnen de sectie</td></tr>
    <tr><td><code>oppervlakteM2</code></td><td>integer</td><td>Kadastrale grootte in m²</td></tr>
    <tr><td><code>soortGrootte</code></td><td>string</td><td>Of de grootte exact of geschat is</td></tr>
    <tr><td><code>perceelId</code></td><td>string</td><td>Identificatie van het perceel</td></tr>
    <tr><td><code>geometrie</code></td><td>object</td><td>GeoJSON, alleen met <code>geometrie=true</code></td></tr>
  </tbody>
</table>
</div>

<h2 id="fouten">Fouten</h2>
<p>Elke fout uit de API zelf heeft deze vorm:</p>
<div class="table-scroll">
<table>
  <thead><tr><th>Veld</th><th>Type</th><th>Toelichting</th></tr></thead>
  <tbody>
    <tr><td><code>fout</code></td><td>string</td><td>Korte omschrijving</td></tr>
    <tr><td><code>code</code></td><td>string</td><td>Machineleesbare code</td></tr>
    <tr><td><code>status</code></td><td>integer</td><td>De HTTP-status</td></tr>
    <tr><td><code>detail</code></td><td>string of object</td><td>Wat er precies misging; soms een object, bijvoorbeeld met een link om op te waarderen</td></tr>
    <tr><td><code>traceId</code></td><td>string</td><td>Vermeld dit bij support</td></tr>
  </tbody>
</table>
</div>
<p>Dat geldt ook voor een 400 door modelvalidatie; <code>detail</code> bevat dan per veld de
meldingen. Match in code op <code>code</code>, niet op de tekst in <code>fout</code>: die tekst kan
wijzigen, de codes niet.</p>

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

<h2>Limieten en credits</h2>
<ul>
  <li>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.</li>
  <li>Een opvraging die op een fout eindigt kost geen credit, en een antwoord zonder WOZ-waarden
    (een lege <code>woz</code>) ook niet.</li>
  <li>Zonder account: een gratis proefsleutel voor 5 unieke adressen via <code>POST /Api/Proef</code>.</li>
  <li>Een lijst: hoogstens 250 adressen met een proefsleutel, 10.000 met een account.</li>
  <li>Saldo in de responseheader <code>X-Credits-Remaining</code>, of via <code>GET /Api/Credits</code>.</li>
  <li>Bij <code>502</code> en <code>503</code> opnieuw proberen met een oplopende wachttijd,
    bijvoorbeeld na 1, 5 en 15 seconden.</li>
</ul>

<div class="cta">
  <h2>Prijzen en account</h2>
  <p>De <a href="https://woz-api.nl/woz-api-prijs">staffels staan publiek</a>, vanaf EUR 0,30 per
  uniek adres excl. btw. Een gratis account geeft 10 credits om de integratie af te maken.</p>
</div>

</div>
</main>

<footer class="bottom">
  <div class="wrap">
    Documentatie bij de WOZ API van <a href="https://woz-api.nl">woz-api.nl</a>.
    Broncode van de clients op <a href="https://github.com/WozApi/wozapi-clients">GitHub</a>, MIT-licentie.
  </div>
</footer>
</body>
</html>