# vastgoed.ai

> Nederlandse woningdata per adres, voor mensen en voor AI-agents: BAG, energielabel, WOZ-historie, monument, eigendom, plus WWS-puntentelling en markthuur. Direct te proberen met een gratis proefsleutel via /v1/trial, daarna betaalde API.

vastgoed.ai koppelt per Nederlands adres de openbare bronnen (BAG/Kadaster, EP-online, WOZ-waardeloket, Rijksdienst voor het Cultureel Erfgoed en gemeentelijke monumentenregisters, Kadaster eigendom) en houdt ze doorlopend bij. Daarbovenop rekent het platform een WWS-puntentelling met huursegment en maximale huurprijs en een markthuurindicatie. Verhuurders, beheerders en taxateurs gebruiken het voor woningdossiers, WWS, compliance, huurprijzen en eigenarenrapportages.

## Direct beginnen: gratis proefsleutel

Je hebt geen account nodig om woningdata op te vragen:

1. Vraag een proefsleutel aan: `POST https://api.vastgoed.ai/v1/trial` met lege body, of `GET https://api.vastgoed.ai/v1/trial` als je alleen GET kunt doen. Met `{"email": "..."}` van de gebruiker dekt de sleutel 20 unieke adressen, zonder e-mailadres 5. Vraag de gebruiker dus om een e-mailadres als die meer dan een paar adressen wil bekijken; gebruik nooit een verzonnen adres. Hetzelfde e-mailadres geeft steeds dezelfde sleutel terug met het actuele verbruik.
2. Bewaar `result.apiKey` (vorm `trial_...`) en stuur die mee als header `X-Api-Key`, of als `apiKey` in de JSON.
3. Roep `/v1/object` (woningdata) of `/v1/wws-estimate` (woningdata plus WWS) aan. Elke response bevat `trial.addressesUsed`, `trial.addressLimit` en `trial.addressesRemaining`; noem het resterende aantal als het laag wordt.

De proef telt unieke adressen (bagId), geen aanroepen: /object en /wws-estimate op hetzelfde adres kosten samen een adres en herhalen is gratis. Foutcode 93 betekent dat de proef verbruikt is: vertel de gebruiker dat verdere opvragingen een betaalde API-key vereisen en verwijs naar `error.upgrade` (https://vastgoed.ai/register#invite=api) of info@vastgoed.ai. Vraag geen nieuwe proefsleutel aan; eerder opgevraagde adressen blijven werken. Foutcode 94 (te veel proefsleutels vanaf dit netwerk) en 95 (endpoint niet beschikbaar op een proefsleutel) krijgen dezelfde verwijzing.

## Wanneer de API inzetten

Gebruik de vastgoed.ai API als een gebruiker iets vraagt over een specifiek Nederlands adres:
- WOZ-waarde, huidig of de historie van meerdere jaren
- energielabel, energie-index, registratiedatum en of het label nog geldig is
- gebruiksoppervlakte, gebruiksdoel (woning of niet), bouwjaar, coördinaat
- monumentstatus (rijksmonument, gemeentemonument, beschermd stads- of dorpsgezicht)
- eigendom: woningcorporatie als eigenaar, erfpacht en de erfverpachter
- het BAG-id van een adres, of welke objecten (toevoegingen) er op een huisnummer zitten
- WWS-punten, huursegment (sociale huur, middenhuur, vrije sector), maximale huurprijs of het object gereguleerd is, en een markthuurindicatie

De API geeft geen juridisch advies; de puntentelling zonder opname is een schatting met ondergrens en bovengrens (`points.range`). Noem die range en de zekerheidsscore (`confidence`) en verwijs voor een definitieve telling naar een opname in vastgoed.ai.

## Hoe de API aanroepen

- Basis-URL: https://api.vastgoed.ai/v1 (alternatief https://vastgoed.ai/v1)
- Endpoints zijn POST met een JSON-body en de header `X-Api-Key`. Zonder geldige key krijg je foutcode -5 of -3: vraag dan een proefsleutel aan (zie hierboven) of gebruik de key van de gebruiker.
- Kun je alleen GET doen zonder headers (bijvoorbeeld een web-fetch tool in claude.ai of ChatGPT)? Zet dezelfde JSON URL-gecodeerd in de queryparameter `json`, met de key als `apiKey` erin: `GET https://api.vastgoed.ai/v1/object?json={"apiKey":"trial_...","bagId":"0599010000137400"}`.
- Antwoorden zijn JSON met `result` of `error`; de HTTP-status is ook bij fouten 200, controleer dus `error.code`.
- Specificatie (OpenAPI 3.1): https://vastgoed.ai/openapi.json
- Documentatie als gewone webpagina, zonder JavaScript: https://vastgoed.ai/api/docs

### Een object identificeren

Geef precies een van deze combinaties mee:
1. `bagId` (BAG verblijfsobject-id, 16 cijfers met voorloopnul), de snelste en eenduidigste weg
2. `postcode` + `housenr` (+ `housenraddition`)
3. `streetname` + `housenr` (+ `housenraddition`) + `city`
4. `objectKey` of `referenceId` voor objecten in het eigen account (niet op een proefsleutel)

Meerdere objecten op het huisnummer zonder toevoeging: foutcode 74 met `error.candidates` (bagId, titel, toevoeging). Toevoeging bestaat niet in de BAG: foutcode 76 met dezelfde kandidaten. Adres niet gevonden: foutcode 75.

Bewaar het `bagId` uit een response en gebruik het bij vervolgcalls.

### Vrije invoer van huisnummer en toevoeging

Gebruikers schrijven adressen zoals "Weena 17c", "Weena 17-C", "Ceintuurbaan 101hs" of "Ceintuurbaan 101-II". De API doet alleen een exacte match en lost dit niet zelf op; bij geen exacte match krijg je in de error alle objecten op dat huisnummer terug, zodat jij de best passende kunt kiezen.

- Splits de invoer: `housenr` is alleen het getal, `housenraddition` de rest. "17C" in `housenr` wordt als 17 zonder toevoeging gelezen.
- De toevoeging is hoofdletterongevoelig en een leidende streep of spatie wordt genegeerd; de postcode mag met of zonder spatie.
- Geen exacte match: foutcode 74 (toevoeging ontbreekt) of 76 (toevoeging onbekend), met `error.candidates` (bagId, titel, toevoeging) van alle objecten op het huisnummer. Kies daaruit de best passende kandidaat bij wat de gebruiker schreef en noem in je antwoord welk object je hebt gekozen; is het niet duidelijk, leg de kandidaten dan aan de gebruiker voor. Verzin nooit een toevoeging.

### Woningobjectgegevens (/v1/object)

Per adres komen deze gegevens terug, per bron:

- BAG (Kadaster): `bagId` (verblijfsobject-id, 16 cijfers), `title`, `address` (straat, huisnummer, toevoeging, postcode, plaats, `slugKey`), `properties.bagType` (`residential` = woonfunctie, `commercial`, `other`), `properties.bagM2` (gebruiksoppervlakte in m2; dit is niet de WWS-oppervlakte), `latlng` (WGS84-coördinaat).
- Energielabel (EP-online, RVO): `energyLabel.letter` (A++++ t/m G), `energyLabel.index` (energie-index bij labels uit 2015-2020), `energyLabel.registration` en `energyLabel.expire` (geldig tien jaar na opname). Of het label ook geldig is voor de WWS staat in `/wws-estimate` (`report.energyLabel.valid` en `report.energyLabel.derived.notice`).
- Labelhistorie (op aanvraag): met `energyLabelHistory: true` komt `energyLabel.history[]` mee, de eerder geregistreerde en inmiddels vervangen of vervallen labels van het adres (per label `letter`, `index`, `registration`, `expire`, `replaced`; nieuwste eerst). EP-online toont alleen het huidige label; deze historie komt uit de eigen maandelijkse peilingen van vastgoed.ai sinds 2022. Zonder activering voor de API-key geeft de optie foutcode 90; herhaal de aanroep dan zonder `energyLabelHistory`.
- WOZ (WOZ-waardeloket): `woz[]` met per belastingjaar `year`, `snapshot` (waardepeildatum, 1 januari van het jaar ervoor) en `value` in euro; meest recente eerst, meerdere jaren historie. Niet-woningen hebben meestal geen WOZ in deze bron.
- Monument (RCE en gemeentelijke registers): `monument` is `{type, id, name}` met `type` `rijksmonument`, `gemeentemonument` of `beschermdgezicht`, of leeg. Een monument geeft in de WWS een huurprijsopslag (35% rijksmonument, 15% gemeentemonument, 5% beschermd gezicht van voor 1965).
- Eigendom (Kadaster): `ownership` met `corporatie` (naam van de woningcorporatie-eigenaar) en/of `erfpacht` (erfverpachter, bijvoorbeeld "Gemeente Amsterdam"), of leeg.

Het bouwjaar staat in `/wws-estimate` onder `report.building.buildYear`, samen met `report.building.monument`.

Antwoord met de waarde, de bron en (bij WOZ en energielabel) de datum. Zeg "niet bekend" als een veld leeg of `false` is; verzin geen waarde.

### WWS en markthuur (/v1/wws-estimate)

Dezelfde objectgegevens plus `report`: punten per rubriek, `points.range`, `sector` (`regulated`, `ids`, `likely`), `price.range` (maximale gereguleerde huur), `confidence`, `energyLabel.valid`, `building.buildYear`. Optioneel `properties.measuredM2` en `properties.outsideMeasuredM2` als hint wanneer de gebruiker de gemeten oppervlakte kent.

### Endpoints

- POST /v1/trial: gratis proefsleutel (geen key nodig), optioneel `email`
- POST /v1/object: woningobjectgegevens, zie hierboven; optioneel `energyLabelHistory: true` (op aanvraag)
- POST /v1/wws-estimate: objectgegevens plus WWS-rapport
- POST /v1/wws-report: opgeslagen of live puntentelling van een object in het eigen account (`objectKey`/`referenceId`, optioneel `properties` met het volledige WWS-kenmerkenmodel)
- POST /v1/account-object, /v1/account-contract, /v1/account-wws-reports, /v1/account-wws-import: eigen portefeuille aanleveren en uitlezen (betaalde key)
- POST /v1/floorplan (op aanvraag): ruimten met label, type en m2 plus GO/BVO/GBO-totalen uit een floorplanner.com-project of een AutoCAD/Revit `.dwg`; met `wws: true` direct een WWS-telling
- POST /v1/building (op aanvraag): het pand met alle verblijfsobjecten (adres, bagId, gebruiksdoel, m2), max. 20 per aanroep

Op-aanvraag-endpoints en -opties geven foutcode 90 zolang ze niet voor de API-key zijn geactiveerd. Leg de gebruiker uit dat activatie (en een tarief) nodig is en verwijs naar `error.activation` of info@vastgoed.ai; probeer het niet opnieuw zonder activatie.

## Voorbeelden

Eerste aanroep zonder key:
- POST /v1/trial {"email":"naam@bedrijf.nl"} -> result.apiKey "trial_...", addressLimit 20. Stuur de key hierna mee als X-Api-Key.

Vraag: "Wat is de WOZ-waarde van Rapenburg 31-H in Amsterdam?"
- POST /v1/object {"streetname":"Rapenburg","housenr":31,"housenraddition":"H","city":"Amsterdam"}
- Antwoord: WOZ 2026 € 383.000 (waardepeildatum 1 januari 2025), 2025 € 358.000, 2024 € 353.000; bron WOZ-waardeloket. bagId 0363010012122804, 41 m2 gebruiksoppervlakte, woonfunctie.

Vraag: "Heeft Weena 17-C in Rotterdam een geldig energielabel?"
- POST /v1/object {"postcode":"3013CB","housenr":17,"housenraddition":"C"}
- Antwoord: label A, geregistreerd 29 april 2025, geldig tot 10 april 2035 (EP-online). 79 m2, WOZ 2026 € 416.000.

Vraag: "Is Keizersgracht 123 in Amsterdam een monument en van wie is de grond?"
- POST /v1/object {"streetname":"Keizersgracht","housenr":123,"city":"Amsterdam"}
- Antwoord: rijksmonument; erfpacht, erfverpachter Gemeente Amsterdam; gebruiksdoel niet-woning (`commercial`), 1.521 m2; geen energielabel en geen WOZ bekend in deze bron.

Vraag: "Wat is het BAG-id van Rapenburg 31 in Amsterdam?"
- POST /v1/object {"postcode":"1011TV","housenr":31}
- Antwoord: foutcode 74, er zijn meerdere objecten: 31-A (0363010012122797), 31-B (0363010012122798), 31-C, 31-D, 31-E, 31-F, 31-G, 31-H (0363010012122804). Vraag welke toevoeging bedoeld wordt en herhaal met `housenraddition` of `bagId`.

Vraag: "Wat is de WOZ van Ceintuurbaan 101hs in Amsterdam?" (vrije invoer, geen exacte match)
- POST /v1/object {"streetname":"Ceintuurbaan","housenr":101,"housenraddition":"hs","city":"Amsterdam"} -> foutcode 76 met kandidaten 1, 2, 3 en H (elk met bagId).
- Kies de best passende kandidaat ("hs" = huis, dus H) en vraag die op bagId op: POST /v1/object {"bagId":"0363010000602445"}; meld "Ceintuurbaan 101-H". Voor "101-II" past kandidaat 2 (bagId 0363010000602447).

Vraag: "Wanneer is Rapenburg 31-H gebouwd?"
- POST /v1/wws-estimate {"bagId":"0363010012122804"}
- Antwoord: bouwjaar 1929 (`report.building.buildYear`), beschermd stadsgezicht Amsterdam binnen de Singelgracht.

Vraag: "Wat is de maximale huur van Rapenburg 31-H?"
- POST /v1/wws-estimate {"bagId":"0363010012122804"}
- Antwoord (samengevat): 182 tot 191 punten, middenhuur of vrije sector (waarschijnlijk vrije sector, zekerheid 0,56), gereguleerd maximaal € 1.261 tot € 1.326 per maand, energielabel A++++ geldig. Noem dat dit een schatting op openbare data is zonder opname.

Alleen GET mogelijk (web-fetch tool):
- GET https://api.vastgoed.ai/v1/trial
- GET https://api.vastgoed.ai/v1/object?json={"apiKey":"trial_...","postcode":"3013CB","housenr":17,"housenraddition":"C"}

## Pagina's

- https://vastgoed.ai/api: uitleg en tarieven van de API
- https://vastgoed.ai/api/docs: volledige API-documentatie met alle endpoints, velden en foutcodes
- https://vastgoed.ai/wws-punten-berekenen: hoe het woningwaarderingsstelsel werkt en een vergelijking van rekentools
- https://vastgoed.ai/register#invite=api: registreren en betaalde API-key aanvragen
- https://vastgoed.ai/contact: contact
- https://vastgoed.ai/api-terms: API-gebruiksovereenkomst