API-integratie vastgoedschatting: technische gids voor ontwikkelaars
Vastgoedwaarderingen zijn lang het domein geweest van PDF-rapporten die per e-mail werden verstuurd. Die tijd is voorbij. Moderne fintech-, proptech- en bankapplicaties hebben waarderingen nodig die realtime beschikbaar zijn binnen een gebruikersflow, inbegrepen in een kredietbeslissing of geïntegreerd in een CRM. Dat vraagt een API-first benadering waarbij waarderingsdata, referentiepunten en marktindicatoren via een stabiele interface worden aangesproken. Deze gids neemt ontwikkelaars mee door de technische aspecten: authenticatie, rate limiting, response-structuur, foutafhandeling en caching-strategieën. De codevoorbeelden zijn generiek en volgen gangbare conventies; raadpleeg altijd de actuele Taxon-documentatie voor exacte endpoints en parameters.
Waarom API-first belangrijk is
Een API-first platform vertrekt van het idee dat elke functionaliteit eerst als gestructureerde interface bestaat, voordat er een UI bovenop komt. Voor vastgoedwaardering betekent dat: je kan honderd panden in een portefeuille in een paar seconden hertaxeren, je kan in een hypotheekapplicatie onmiddellijk een indicatieve waarde tonen, en je kan waarderingen combineren met eigen databronnen zonder handmatige tussenstappen.
Bij een platform met meer dan een miljoen gehistoriseerde transacties en miljoenen gestructureerde beeldpunten is de API de enige schaalbare manier om die rijkdom aan te spreken. Response-tijden onder de 200 ms maken het mogelijk om waarderingen synchroon in een gebruikersflow op te nemen, zonder dat je naar een asynchrone queue moet uitwijken.
Authenticatie: keys, OAuth en rate limiting
De meeste zakelijke waarderings-API's werken met een van deze drie authenticatiemechanismen:
API-keys (Bearer tokens)
De eenvoudigste variant. Je ontvangt een key die je meestuurt in de Authorization-header. Keys worden gescoped per omgeving (sandbox, productie) en per toepassing. Roteer ze periodiek en bewaar ze nooit in clientcode of publieke repositories.
OAuth 2.0 client credentials
Gebruikt bij integraties waar meerdere dienstverleners eenzelfde API aanspreken. Je app vraagt met een client_id en client_secret een kortlevende access_token aan, die je vervolgens meestuurt. Voordeel: gecompromitteerde tokens zijn snel verlopen.
mTLS of certificaatgebaseerd Voor bank- en verzekeraarintegraties waar PSD2-achtige beveiligingseisen gelden. De client authenticeert met een certificaat dat op infrastructuurniveau wordt gevalideerd.
Rate limits verschillen per plan, maar volgen doorgaans een tokenbucket-patroon. Verwacht headers zoals X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset in elke response. Bij overschrijding krijg je een 429 Too Many Requests met een Retry-After-header.
Response-formaat: value, confidence en comparables
Een goed gestructureerde waarderingsresponse bevat meer dan alleen een getal. Typisch zie je:
{
"valuation_id": "val_8f2a9b1c",
"timestamp": "2026-04-22T14:32:11Z",
"property": {
"address": "Diksmuidseweg 123, 8900 Ieper",
"niscode": "33011",
"type": "house",
"living_area_m2": 165,
"plot_area_m2": 340,
"construction_year": 1998,
"epc_kwh_m2_year": 192
},
"value": 348000,
"confidence_low": 325000,
"confidence_high": 371000,
"confidence_score": 0.82,
"currency": "EUR",
"referentiepunten": [
{
"distance_m": 180,
"sold_date": "2025-11-14",
"sold_price": 342000,
"similarity_score": 0.91
}
],
"market_context": {
"median_niscode_house": 315000,
"trend_12m_pct": 2.4
}
}
De value is de puntwaardeschatting. De confidence_low en confidence_high vormen een betrouwbaarheidsinterval, doorgaans met een dekking van 80 tot 90 procent. Respecteer deze marges in je UI: toon nooit alleen het puntschatting zonder context over onzekerheid.
De lijst van referentiepunten bevat vergelijkbare transacties die de waardering onderbouwen. Voor een klant betekent dat transparantie; voor een ontwikkelaar betekent dat je eigen logica erbovenop kan leggen, bijvoorbeeld om alleen transacties van de laatste 18 maanden mee te wegen.
Code-voorbeelden
Hieronder vind je minimale voorbeelden in Python, JavaScript en PHP voor een fictief endpoint POST /api/valuation. Vervang YOUR_API_KEY door je eigen token.
Python met requests
import requests
API_URL = "https://api.taxonapi.be/api/valuation"
API_KEY = "YOUR_API_KEY"
payload = {
"address": "Diksmuidseweg 123, 8900 Ieper",
"type": "house",
"living_area_m2": 165,
"plot_area_m2": 340,
"construction_year": 1998,
"epc_kwh_m2_year": 192,
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=5,
)
if response.status_code == 200:
data = response.json()
print(f"Waarde: EUR {data['value']:,}")
print(f"Interval: EUR {data['confidence_low']:,} - EUR {data['confidence_high']:,}")
elif response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 1))
print(f"Rate limit bereikt, wacht {retry_after} s")
else:
response.raise_for_status()
JavaScript met fetch
const API_URL = "https://api.taxonapi.be/api/valuation";
const API_KEY = process.env.VALUATION_API_KEY;
async function getValuation(property) {
const response = await fetch(API_URL, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(property),
});
if (response.status === 429) {
const retryAfter = Number(response.headers.get("Retry-After") ?? 1);
throw new Error(`Rate limited, retry na ${retryAfter}s`);
}
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
return response.json();
}
getValuation({
address: "Diksmuidseweg 123, 8900 Ieper",
type: "house",
living_area_m2: 165,
plot_area_m2: 340,
construction_year: 1998,
epc_kwh_m2_year: 192,
})
.then((data) => {
console.log(`Waarde: EUR ${data.value.toLocaleString("nl-BE")}`);
})
.catch(console.error);
PHP met curl
<?php
$apiUrl = 'https://api.taxonapi.be/api/valuation';
$apiKey = getenv('VALUATION_API_KEY');
$payload = [
'address' => 'Diksmuidseweg 123, 8900 Ieper',
'type' => 'house',
'living_area_m2' => 165,
'plot_area_m2' => 340,
'construction_year' => 1998,
'epc_kwh_m2_year' => 192,
];
$ch = curl_init($apiUrl);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($statusCode === 200) {
$data = json_decode($response, true);
printf("Waarde: EUR %s\n", number_format($data['value'], 0, ',', '.'));
} elseif ($statusCode === 429) {
echo "Rate limit bereikt, probeer opnieuw\n";
} else {
throw new RuntimeException("API error: $statusCode");
}
Best practices voor confidence intervals
Een puntschatting zonder interval is misleidend. Enkele vuistregels:
- Toon altijd de marge. UI's die alleen "EUR 348.000" tonen, wekken valse zekerheid. Een bereik zoals "EUR 325k - EUR 371k" is eerlijker.
- Schaal confidence naar gebruik. Voor een kredietbeslissing op de exacte puntschatting vertrouwen is riskant; neem de onderkant van de 80-procent-marge als conservatieve basis.
- Interpreteer confidence_score conservatief. Een score van 0.85 betekent dat het model zelfverzekerd is gegeven de beschikbare data, niet dat er 85 procent kans is dat het pand exact die waarde heeft.
- Vul AVM aan met menselijke expertise bij grenswaarden. Een AVM complementeert een erkend schatter; voor complexe panden of bij grote financiële beslissingen blijft een manuele schatting de norm.
Caching-strategie
Waarderingen zijn niet volledig statisch, maar ook niet realtime-gevoelig op seconde-niveau. Een pragmatische aanpak:
- Cache per pand-hash voor 24 uur in een Redis of Memcached laag. Gebruik een deterministische hash van de input (adres + woninggegevens) als key.
- Bust de cache bij wijziging van kenmerken. Wanneer living_area of EPC wijzigt, invalideer je de entry.
- Respecteer cache-headers van de API.
Cache-ControlenETaggeven je hints over hergebruik. - Pas stale-while-revalidate toe voor dashboards die snelheid boven verse data prefereren.
Voor marktdata zoals de prijskaart per niscode kan je rustig langer cachen: die update doorgaans maandelijks.
Error handling
Een robuuste integratie behandelt minstens deze scenario's:
400 Bad Request -> valideer input aan je kant, stuur niet opnieuw
401 Unauthorized -> key invalid of verlopen, roteer en probeer opnieuw
403 Forbidden -> scope ontbreekt, contacteer account manager
404 Not Found -> adres niet geocodeerbaar, val terug op handmatige input
422 Unprocessable -> data onvolledig, vraag ontbrekende velden bij gebruiker op
429 Too Many Requests -> exponentiële backoff met Retry-After
500/502/503 -> retry met backoff, maximaal 3 pogingen, circuit breaker
Log elke non-2xx response inclusief de valuation_id of correlatie-ID die de API teruggeeft. Dat vergemakkelijkt supportaanvragen aanzienlijk.
Conclusie
Een vastgoedschatting-API goed integreren vraagt meer dan een enkele POST-request. Solide authenticatie, respect voor rate limits, correcte interpretatie van confidence-intervallen en een doordachte caching- en error-strategie maken het verschil tussen een fragile integratie en een productierijpe oplossing.
Klaar om te beginnen? Raadpleeg de technische documentatie voor endpoints en parameters, ontdek het valuatieproduct, of neem contact op voor een sandbox-toegang.
Disclaimer: code-voorbeelden zijn illustratief en gebaseerd op generieke REST-conventies. Exacte endpoints, payloads en foutcodes kunnen verschillen per API-provider. Test altijd tegen een sandbox voor je in productie gaat.
Bouw op de Taxon API
Volledige OpenAPI-documentatie en developer support voor je PropTech-integratie.