woz-api-nl Adressen API

openapi: 3.2.0
info:
  title: Wozapi Adressen API
  description: 'De WOZ API die je zelf regelt. WOZ-waarden, BAG-adresgegevens met bouwjaar en oppervlakte, WOZ-object en kadastrale percelen uit 1 endpoint. Met `energielabel=true` ook het geregistreerde energielabel (EP-Online van RVO), zonder extra credit.


    **Base URL:** `https://woz-api.nl`


    **Authenticatie:** stuur je key mee als header `X-Api-Key: {key}` of als `Authorization: ApiKey {key}`. Een key maak je aan onder API sleutels. Een sleutel hoort in een header, nooit in een URL.


    **Voor softwareleveranciers (OAuth-koppeling):** laat je klant zijn eigen Wozapi-account koppelen via OAuth 2.0 (authorization code met PKCE) en stuur diens access token mee als `Authorization: Bearer {token}`. De credits gaan dan van het account van je klant af. Scopes: `woz.lookup` en `account.saldo`. Discovery: `/.well-known/openid-configuration`. Uitleg en aanvraag: woz-api.nl/woz-api-koppeling.


    **Credits:** 1 credit is 1 uniek adres. Hetzelfde adres binnen 7 dagen opnieuw opvragen kost geen extra credit; dat is een kortingsregel en geen cache, de request wordt wel echt uitgevoerd. Een opvraging die op een fout eindigt (4xx of 5xx) kost niets, en een antwoord zonder WOZ-waarden (een lege `woz`) ook niet. Een nieuw account krijgt 10 gratis credits. Het resterende saldo staat in de response-header `X-Credits-Remaining` en is ook op te vragen via `GET /Api/Credits`. Is het saldo op, dan volgt 402 met code `InsufficientCredits`.


    **Zonder account:** vraag een gratis proefsleutel aan met `POST /Api/Proef` (5 unieke adressen, 10 met het e-mailadres van de gebruiker) en stuur hem mee als `X-Api-Key`. Zonder sleutel geeft de API 401 met code `SleutelOntbreekt`; een verbruikte proef geeft 402 met code `ProefVerbruikt`.


    **Een hele lijst:** `POST /Api/Lijst` met de adressen geeft een gratis proef van 5 adressen, de prijs voor de hele lijst en een betaalpagina voor de gebruiker; na betaling de rijen en het bestand.


    **AI-assistenten:** een MCP-server op `https://woz-api.nl/Api/Mcp`, en uitleg voor agents op woz-api.nl/voor-ai-agents.


    **Foutvorm:** elke fout geeft `{ fout, code, status, detail, traceId }` terug, zie het schema ApiFoutResponse. 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`. Veelvoorkomende codes: `InvalidInput` (400), `Unauthorized` (401), `InsufficientCredits` (402), `AddressNotFound` (404), `PdokLookupFailed` (502) en `UpstreamUnavailable` (503). Een 502 of 503 kost niets; probeer het opnieuw, bij een 503 na het aantal seconden uit de header `Retry-After`, en sla het adres niet over.


    **Geen WOZ-waarde:** alleen van woningen is de WOZ-waarde openbaar. Bestaat het adres maar is er geen openbare waarde, bijvoorbeeld bij een kantoor of kerk, dan krijg je een 200 met een lege `woz`, `huidigeWaarde: null` en in `wozStatus` de reden: `geen_woning` als het pand volgens de BAG geen woonfunctie heeft, anders `geen_waarde`. Dat is een antwoord en geen storing: opnieuw proberen verandert niets, en het kost geen credit. Een storing geeft altijd een 502 of 503.


    **Voorbeeld:**


    ```

    curl "https://woz-api.nl/Api/Adres?adres=Spuistraat%2036C,%201012TT%20Amsterdam" \

    -H "X-Api-Key: JOUW_API_KEY"

    ```'
  termsOfService: https://woz-api.nl/terms
  contact:
    name: Wozapi
    url: https://woz-api.nl/
    email: info@woz-api.nl
  version: v1
servers:
- url: https://woz-api.nl
  description: Productie
security:
- ApiKey: []
tags:


# --- truncated at 32 KB (45 KB total) ---
# Full source: https://artifacts.apis.io/woz-api-nl/openapi/woz-api-nl-adressen-api-openapi.yml