De WOZ API in gewone taal
Je stuurt een adres, je krijgt de WOZ-waarden terug. Deze pagina legt uit hoe dat werkt, wat er in het antwoord staat en wat het kost. Ook als je zelf niet programmeert.
Probeer het nu
5 gratis, zonder accountJe vraagt hiermee echt de WOZ-waarde op. Zonder account krijg je een gratis proef van 5 adressen; hetzelfde adres opnieuw telt niet mee.
Let op de volgorde: woz loopt van oud naar nieuw, dus woz[0]
is de oudste peildatum. Gebruik huidigeWaarde voor de meest recente.
Wat doet deze API?
De API zoekt bij een Nederlands adres de bijbehorende WOZ-waarde op, zoals de gemeente die heeft vastgesteld. Je krijgt niet alleen het bedrag, maar ook de vaste sleutels uit de Basisregistratie Adressen en Gebouwen en het perceel uit het Kadaster.
Perceelgegevens zijn gebaseerd op de Kadastrale Kaart, © Kadaster, licentie CC BY 4.0.
Een gemeente stelt de WOZ-waarde vast per 1 januari van een jaar. Dat moment heet de peildatum. Omdat er meerdere jaren bekend kunnen zijn, krijg je een reeks terug en niet één getal.
In drie stappen aan de slag
- Maak een account. Je krijgt 10 gratis credits en je API-sleutel staat meteen klaar op je dashboard. Je hoeft niets aan te maken.
- Probeer het zonder code. Vul hierboven een adres in en bekijk het antwoord in gewone taal. Zo weet je zeker dat je het juiste opvraagt.
- Zet het in je software. Kopieer hieronder het voorbeeld in jouw taal. Werk je niet zelf in code? Stuur dit blok door naar je developer.
Je sleutel meesturen
Elke aanvraag stuurt je sleutel mee in de header X-Api-Key. Nog geen account? Een
gratis proefsleutel voor vijf adressen vraag je aan met POST https://woz-api.nl/Api/Proef;
de tester hieronder doet dat vanzelf. Werk je met een AI-assistent, kijk dan op
WozApi voor AI-agents.
Een adres opvragen
Het adres geef je als één tekst mee, bijvoorbeeld Spuistraat 36C, 1012 TT Amsterdam. Geef altijd de postcode of de plaats mee. Zonder die twee nemen we de eerste treffer, en "Kerkstraat 12" bestaat in veel plaatsen: dan krijg je misschien de WOZ-waarde van een ander pand.
curl "https://woz-api.nl/Api/Adres?adres=Spuistraat%2036C%2C%201012%20TT%20Amsterdam" \
-H "X-Api-Key: JOUW_API_SLEUTEL"
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Api-Key", "JOUW_API_SLEUTEL");
var adres = Uri.EscapeDataString("Spuistraat 36C, 1012 TT Amsterdam");
var json = await http.GetStringAsync($"https://woz-api.nl/Api/Adres?adres={adres}");
// woz staat oplopend: woz[0] is de oudste peildatum. huidigeWaarde is de nieuwste.
using var doc = System.Text.Json.JsonDocument.Parse(json);
var huidig = doc.RootElement.GetProperty("huidigeWaarde");
Console.WriteLine(huidig.GetProperty("vastgesteldeWaarde").GetInt32());
// Vanaf je server (Node 18 of nieuwer), niet in de browser: daar staat je sleutel voor iedereen open.
const adres = encodeURIComponent("Spuistraat 36C, 1012 TT Amsterdam");
const res = await fetch(`https://woz-api.nl/Api/Adres?adres=${adres}`, {
headers: { "X-Api-Key": "JOUW_API_SLEUTEL" }
});
if (!res.ok) throw new Error(`WozApi gaf status ${res.status}`);
const data = await res.json();
// woz staat oplopend: woz[0] is de oudste peildatum. huidigeWaarde is de nieuwste.
console.log(data.huidigeWaarde.vastgesteldeWaarde, data.huidigeWaarde.peildatum);
import requests
res = requests.get(
"https://woz-api.nl/Api/Adres",
params={"adres": "Spuistraat 36C, 1012 TT Amsterdam"},
headers={"X-Api-Key": "JOUW_API_SLEUTEL"},
timeout=30,
)
res.raise_for_status()
# woz staat oplopend: woz[0] is de oudste peildatum. huidigeWaarde is de nieuwste.
huidig = res.json()["huidigeWaarde"]
print(huidig["vastgesteldeWaarde"], huidig["peildatum"])
{
"adres": "Spuistraat 36C, 1012TT Amsterdam",
"bag": {
"adresseerbaarobjectId": "0363010000816946",
"nummeraanduidingId": "0363200000418472",
"straatnaam": "Spuistraat",
"huisnummer": 36,
"postcode": "1012TT",
"woonplaatsnaam": "Amsterdam",
"bouwjaar": 1725,
"oppervlakte": 56,
"gebruiksdoelen": ["woonfunctie"],
"pandIds": ["0363100012170994"]
},
"wozObject": { "wozobjectnummer": 36300285811 },
"percelen": [
{ "aanduiding": "ASD04 F 1145", "oppervlakteM2": 92 }
],
"woz": [
{ "peildatum": "2025-01-01", "vastgesteldeWaarde": 662000 }
],
"huidigeWaarde": { "peildatum": "2025-01-01", "vastgesteldeWaarde": 662000 },
"wozStatus": "gevonden"
}
| Taal | Installeren | Pakketpagina |
|---|---|---|
| Python 3.9+ | pip install wozapi |
PyPI |
| Node.js 18+ | npm install wozapi |
npm |
| .NET 8+ | dotnet add package WozApi.Client |
NuGet |
Een lijst adressen
Heb je een Excel of CSV met adressen en wil je per rij de WOZ-waarde erbij? Zonder code upload je het bestand op WOZ-waarden bij een lijst adressen in Excel: een gratis proef met 5 adressen, de prijs vooraf, en hetzelfde bestand terug. Met code, bijvoorbeeld een script dat een AI-assistent voor je schrijft, doe je per adres een aanroep. Dit is het hele recept; een adres zonder WOZ-waarde kost geen credit, en een fout ook niet.
# pip install requests openpyxl
import time
import openpyxl
import requests
API = "https://woz-api.nl/Api/Adres"
SLEUTEL = "woz_..." # je API-sleutel; altijd in de header, nooit in een URL
BESTAND = "adressen.xlsx" # kolom A: straat en huisnummer, B: postcode, C: plaats
wb = openpyxl.load_workbook(BESTAND)
ws = wb.active
ws.cell(row=1, column=4, value="WOZ-waarde")
ws.cell(row=1, column=5, value="Peildatum")
ws.cell(row=1, column=6, value="Status")
s = requests.Session()
s.headers["X-Api-Key"] = SLEUTEL
def vraag(params):
# Bij een storing (502, 503) of te snel (429) zegt Retry-After hoe lang je wacht. Sla het
# adres niet over: een storing duurt meestal minuten, en opnieuw proberen kost niets.
for poging in range(6):
r = s.get(API, params=params, timeout=30)
if r.status_code not in (429, 502, 503):
return r
time.sleep(int(r.headers.get("Retry-After", 10 * (poging + 1))))
return r
for rij in range(2, ws.max_row + 1):
straat, postcode, plaats = (ws.cell(rij, k).value for k in (1, 2, 3))
if not straat or not (postcode or plaats):
ws.cell(rij, 6, "overgeslagen: geen adres of geen postcode en plaats")
continue
adres = f"{straat}, {postcode or ''} {plaats or ''}".strip()
r = vraag({"adres": adres})
if r.status_code == 200:
d = r.json()
huidig = d.get("huidigeWaarde")
if huidig:
ws.cell(rij, 4, huidig["vastgesteldeWaarde"])
ws.cell(rij, 5, huidig["peildatum"])
ws.cell(rij, 6, d.get("wozStatus")) # gevonden, geen_woning of geen_waarde
elif r.status_code == 402:
print("Saldo op. Opwaarderen:", r.json().get("detail", {}).get("opwaarderen"))
break
else:
ws.cell(rij, 6, r.json().get("code", str(r.status_code))) # AddressNotFound, of na een lange storing UpstreamUnavailable: draai die rijen later opnieuw
time.sleep(0.2)
wb.save("adressen-met-woz.xlsx")
Elke rij heeft straat en huisnummer samen in een cel nodig, plus een postcode of een plaats.
Zonder postcode of plaats nemen we de eerste treffer in het land. Een assistent met een
HTTP-tool kan de lijst ook in een keer aanleveren via POST /Api/Lijst; zie
WozApi voor AI-agents.
Werk je met een AI-assistent? Plak dit erin:
Ik heb een lijst Nederlandse adressen en wil per adres de WOZ-waarde erbij. Gebruik de WOZ API van woz-api.nl: het recept staat op https://woz-api.nl/docs#een-lijst-adressen (aanroep per adres met de header X-Api-Key; een adres zonder WOZ-waarde kost geen credit). Mijn sleutel geef ik je apart. Schrijf het script en zeg me wat ik moet doen.
Wat krijg je terug?
Het antwoord bevat deze onderdelen:
- adres
- Het gevonden adres Zoals het in de Basisregistratie Adressen en Gebouwen staat. Handig om te controleren of je het juiste pand te pakken hebt.
- huidigeWaarde
-
De meest recente WOZ-waarde
Dit is wat je in de meeste gevallen nodig hebt: de nieuwste vastgestelde waarde met de bijbehorende peildatum. Is er geen enkele waarde bekend, dan staat hier null en zegt
wozStatuswaarom. - wozStatus
-
Of er een WOZ-waarde is, en zo niet waarom
gevondenals er waarden zijn.geen_woningals het pand volgens de Basisregistratie Adressen en Gebouwen geen woonfunctie heeft: alleen van woningen is de WOZ-waarde openbaar.geen_waardeals er geen waarde is terwijl het gebruiksdoel een woonfunctie noemt of niet bekend is. Een legewozis een antwoord en geen storing: opnieuw proberen verandert niets, en het kost geen credit. - woz
- Alle WOZ-waarden per peildatum Een lijst met per jaar de vastgestelde waarde in hele euro's; de peildatum is steeds 1 januari. Let op de volgorde: de lijst loopt van oud naar nieuw, dus het eerste element is de oudste waarde en het laatste de nieuwste. Wil je alleen de actuele waarde, gebruik dan huidigeWaarde.
- wozObject
- Het WOZ-object zelf Met het objectnummer uit de landelijke WOZ-registratie en, als het bekend is, de grondoppervlakte in vierkante meters.
- bag
- Vaste sleutels van het adres, plus bouwjaar en oppervlakte De nummeraanduiding en het verblijfsobject: bewaar die in je eigen database, ze veranderen niet als een straatnaam of schrijfwijze wijzigt. Daarnaast het oorspronkelijke bouwjaar, de gebruiksoppervlakte in m² en het gebruiksdoel uit de Basisregistratie Adressen en Gebouwen. Veel isolatieregelingen stellen een bouwjaar als voorwaarde, dus die toets je in dezelfde aanroep.
- energielabel
-
Alleen met
?energielabel=trueHet geregistreerde energielabel uit EP-Online van RVO: de klasse, tot wanneer het geldt en het woningtype. Kijk eerst naarstatus:gevonden,geen_labelofniet_beschikbaar. Het kost geen extra credit. - subsidietoets
-
Alleen met
?subsidietoets=trueDe toets aan de gemeentelijke regelingen met een WOZ-grens, zoals een isolatiesubsidie: de gemeente van het adres, en per regeling of de woning onder de grens valt (uitkomst), op de peildatum die de regeling noemt, met bouwjaar en, metenergielabel=true, het label. Wat per adres niet te weten is, staat ondernogNaTeGaan. Elke gemeente is nagelezen; zie het overzicht per gemeente. Het kost geen extra credit. - percelen
- Het kadastrale perceel Aanduiding en oppervlakte volgens de open Kadastrale Kaart, bijvoorbeeld ASD04 F 1145.
Wat het kost
- Eén geslaagde opvraag van een nieuw adres kost 1 credit.
- Een fout kost niets, en een antwoord zonder WOZ-waarde ook niet.
- Hetzelfde adres nog eens opvragen is 7 dagen lang gratis.
- Een nieuw account start met 10 gratis credits.
- Je resterende saldo staat in elke respons in de header
X-Credits-Remaining.
Als er iets misgaat
Bij een fout krijg je een JSON-antwoord met de velden fout, code, status, detail en traceId. Reageer in code op code: die verandert niet, de tekst in fout wel.
| Status | Wat het betekent | Wat je doet |
|---|---|---|
400 |
Het verzoek klopt niet: geen adres meegegeven, of een BAG-id dat geen 16 cijfers is. | Controleer de parameter adres of het id. |
401 |
De sleutel ontbreekt of klopt niet. | Controleer de header X-Api-Key. |
402 |
Je credits zijn op (InsufficientCredits). |
Waardeer op via je account. |
401 of 402 |
Geen sleutel meegestuurd (SleutelOntbreekt), of de gratis proef is op (ProefVerbruikt). |
Vraag een proefsleutel aan, of maak een account aan en stuur je sleutel mee. |
404 |
Dit adres is niet gevonden (AddressNotFound). |
Controleer de schrijfwijze, of vul postcode en plaats aan. |
200 met een lege woz |
Het adres bestaat, maar er is geen openbare WOZ-waarde. wozStatus zegt waarom: geen_woning (alleen woningen hebben een openbare WOZ-waarde) of geen_waarde. |
Niet opnieuw proberen: het antwoord blijft hetzelfde. Het kost geen credit. |
502 503 |
Een bron achter ons is tijdelijk niet bereikbaar of te traag. Dit ligt aan ons, niet aan je verzoek. | Probeer het opnieuw. Staat er een Retry-After-header bij (bij een storing 60 seconden), wacht dan zo lang; anders met een oplopende wachttijd, bijvoorbeeld na 1, 5 en 15 seconden. Sla het adres niet over: deze fouten kosten geen credit. |
Klaar om te beginnen?
Je sleutel staat direct klaar en je eerste tien opvragen zijn gratis.