Aan de slag

Van niets naar een WOZ-waarde in je eigen code. Reken op een paar minuten, waarvan het meeste het aanmaken van een account is.

1. Een sleutel aanmaken

Maak een gratis account op woz-api.nl en genereer een sleutel onder API sleutels. Je krijgt 10 credits, genoeg om de integratie af te maken voordat je iets betaalt.

Wil je eerst zien wat je terugkrijgt zonder account, dan staat er een live demo met een echte respons op de homepage, en de volledige OpenAPI-definitie in Swagger.

2. De eerste call

De sleutel gaat mee als header. Twee vormen werken:

Header	Waarde
`X-Api-Key`	`{jouw sleutel}`
`Authorization`	`ApiKey {jouw sleutel}`

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

Url-encodeer het adres. Een adres bevat spaties en vaak een komma. Zonder encoding kapt je shell of HTTP-client de parameter af bij de eerste spatie en krijg je een 400 terug op een adres dat gewoon bestaat.

3. De respons lezen

De waarden staan in de reeks woz, met per element een peildatum en een vastgesteldeWaarde. Een adres heeft doorgaans meerdere peildata. Wil je de meest recente waarde, sorteer dan op peildatum in plaats van blind het eerste element te pakken: de volgorde is geen contract.

import json, urllib.parse, urllib.request

url = "https://woz-api.nl/Api/Adres?" + urllib.parse.urlencode(
    {"adres": "Spuistraat 36C, 1012TT Amsterdam"})
verzoek = urllib.request.Request(url, headers={"X-Api-Key": "JOUW_API_KEY"})

with urllib.request.urlopen(verzoek) as antwoord:
    data = json.load(antwoord)

recentste = max(data["woz"], key=lambda w: w["peildatum"])
print(recentste["peildatum"], recentste["vastgesteldeWaarde"])

Voor Python, Node.js en .NET staat er een client die dit voor je doet, zie Clients.

Wat er mis kan gaan

Status	Betekenis	Wat te doen
`400`	Adres onleesbaar of parameter ontbreekt	Controleer de url-encoding en of `adres` is meegestuurd
`401`	Sleutel ontbreekt of is ongeldig	Header `X-Api-Key` controleren; een ingetrokken sleutel geeft ook 401
`403`	Anoniem limiet bereikt	Zonder account mag je 5 adressen per IP; maak een account aan
`404`	Geen WOZ-object bij dit adres	Kan legitiem zijn: niet elk BAG-adres heeft een WOZ-object
`429`	Te veel requests	Bouw exponentiële backoff in en verlaag je gelijktijdigheid

Een fout heeft altijd dezelfde vorm, zodat je er één handler voor kunt schrijven:

{
  "fout": "korte omschrijving",
  "code": "machineleesbare code",
  "status": 400,
  "detail": "wat er precies misging",
  "traceId": "id voor support"
}

Uitzondering: een 400 door modelvalidatie komt van ASP.NET zelf en heeft de ValidationProblemDetails-vorm met een errors-object. Vang dus op status, niet op de aanwezigheid van fout.

Credits en herhaalverkeer

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 echt uitgevoerd. Een mislukte lookup kost niets. Je saldo staat in de responseheader X-Credits-Remaining en is ook op te vragen via GET /Api/Credits.

Volgende stap

De referentie heeft alle endpoints en velden. Werk je liever zonder code, dan vult de Excel-wizard een bestand met adressen in één keer aan.