WOZ API-koppeling maken: stapsgewijze handleiding

Een WOZ API-koppeling laat je software automatisch de WOZ-waarde en BAG-adresgegevens ophalen. In deze praktische handleiding lees je stap voor stap hoe je de koppeling maakt: van account en API-key tot authenticatie, endpoints, codevoorbeelden en foutafhandeling. Zo staat je WOZ API-koppeling binnen enkele minuten live.

Wat is een WOZ API-koppeling?

Een WOZ API-koppeling is de integratie tussen jouw applicatie en de WozApi-webservice. Je applicatie stuurt een HTTP-verzoek met een adres, en krijgt de WOZ-waarde en BAG-gegevens terug als JSON. De koppeling werkt met elke taal of tool die HTTP-requests kan versturen.

Stap 1: account en API-key aanmaken

Maak eerst een gratis account aan; je ontvangt 10 gratis credits om te testen. Genereer daarna een API-key op de pagina API-keys. Bewaar deze sleutel veilig, want je gebruikt hem bij elk verzoek.

Stap 2: authenticatie met X-Api-Key

Authenticatie gaat via een header. Stuur je API-key mee als X-Api-Key:

X-Api-Key: JOUW_API_KEY

Verzoeken zonder geldige sleutel krijgen een 401 Unauthorized terug.

Stap 3: je eerste call

curl "https://woz-api.nl/Api/Adres?adres=Damrak 1, 1012LG Amsterdam" \
  -H "X-Api-Key: JOUW_API_KEY"

Response:

{
  "adres": "Damrak 1, 1012LG Amsterdam",
  "bag": { "straatnaam": "Damrak", "huisnummer": 1, "postcode": "1012LG", "woonplaatsnaam": "Amsterdam" },
  "woz": [ { "peildatum": "2024-01-01", "vastgesteldeWaarde": 512000 } ]
}

Endpoints in het kort

• GET /Api/Adres?adres=...: WOZ-waarde en BAG-gegevens op basis van een adres;
• GET /Api/Nummeraanduiding/{id}: opvragen op BAG-nummeraanduiding;
• GET /Api/AdresseerbaarObject/{id}: opvragen op BAG adresseerbaar object;
• GET /Api/Credits: je resterende creditsaldo.

De volledige specificatie met parameters en responses vind je in de Swagger-documentatie.

Codevoorbeelden

C# (HttpClient):

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "JOUW_API_KEY");
var json = await client.GetStringAsync(
  "https://woz-api.nl/Api/Adres?adres=Damrak 1, 1012LG Amsterdam");

Python (requests):

import requests
r = requests.get(
    "https://woz-api.nl/Api/Adres",
    params={"adres": "Damrak 1, 1012LG Amsterdam"},
    headers={"X-Api-Key": "JOUW_API_KEY"},
)
print(r.json())

Credits, caching en foutafhandeling

• Credits: 1 credit per uniek adres. Hetzelfde adres binnen 7 dagen opnieuw opvragen kost geen extra credit. Dat is een kortingsregel en geen cache: de request gaat wel echt naar de API, dus caching aan jouw kant blijft nuttig als je dezelfde adressen vaak opvraagt.
• 402 Payment Required: je credits zijn op. Koop credits bij op de prijzenpagina en de koppeling werkt direct verder.
• 401 Unauthorized: ontbrekende of ongeldige API-key.
• Saldo bewaken: vraag periodiek /Api/Credits op om je resterende saldo te tonen of te loggen.

Checklist om live te gaan

1. Account aangemaakt en 10 gratis credits ontvangen;
2. API-key gegenereerd en veilig opgeslagen (niet in client-side code);
3. Adres-endpoint getest met een echt adres;
4. Foutafhandeling voor 401 en 402 ingebouwd;
5. Creditsaldo-bewaking ingericht.

Meer achtergrond over wat je terugkrijgt lees je in WOZ-waarde opvragen via een API en BAG API Nederland.