Documentatie

Algemene conventies

De envelop

Elk succesvol antwoord heeft dezelfde buitenkant, ongeacht de API:

{
  "api": "nederland.cloud",
  "versie": "v1 (bèta)",
  "onderdeel": "bag.adressen",          // welke API u aanriep
  "bron_type": "bron-api",              // 'bron-api' of 'dataset' — zie algemene conventies
  "gegenereerd_op": "2026-08-20T19:12:03Z",
  "duur_ms": 312,                        // totale responstijd
  "bronnen": [{                          // herkomst van dít antwoord
    "naam": "PDOK Locatieserver",
    "instantie": "Kadaster / PDOK",
    "licentie": "CC0 1.0",
    "duur_ms": 280,
    "uit_cache": false,
    "status": "ok"
  }],
  "data": { ... }                        // de genormaliseerde inhoud
}

Bij CC BY-bronnen (zoals CBS) bevat bronnen[] tevens een verplicht attributie-veld dat u bij hergebruik dient mee te geven.

Foutafhandeling

Alle fouten — ook wanneer een bron onbereikbaar is — volgen RFC 7807:

HTTP/1.1 400 Bad Request
{
  "type": "about:blank",
  "title": "Parameter 'q' is verplicht (minimaal 2 tekens)",
  "status": 400
}

Dataverificatie & integriteit

Elk antwoord is onafhankelijk verifieerbaar. Drie mechanismen:

1. Hash over de genormaliseerde data

Elke response bevat integriteit.hash: een SHA-256 over de canonieke JSON van data. U herberekent die hash en vergelijkt — zo weet u dat het antwoord niet onderweg is gewijzigd:

import hashlib, json

canoniek = json.dumps(antwoord["data"], sort_keys=True,
                      separators=(",", ":"), ensure_ascii=False)
hash = hashlib.sha256(canoniek.encode("utf-8")).hexdigest()
assert hash == antwoord["integriteit"]["hash"]   # 1:1

2. Exacte bron-URL per antwoord

Elke bronnen[]-registratie bevat bron_url: de exacte aanroep die wij bij de instantie deden (parameters incluis). Haal die zelf op en vergelijk de ruwe bron met onze genormaliseerde weergave — er mag inhoudelijk niets anders verschillen dan formaatnormalisatie.

3. Normalisatiebeleid (wat wij wél en niét veranderen)

Wij veranderen nooit inhoud. Alleen formaat: coderingen naar snake_case, datums naar ISO-8601, CBS-'onbekend'-codes naar null, coördinaten naar WGS84 (+RD), getallen naar getallen. Ontbrekende of afgeschermde bronwaarden worden null — nooit ingevuld, geschat of gecorrigeerd.

Standaarden

Op de roadmap: ondertekende responses (HMAC met klantsleutel), een publiek auditlog van bron-versies, en ISO/IEC 27001-certificering van de hosting.

Zoekt adressen in de Basisregistratie Adressen en Gebouwen: straat, huisnummer, postcode, woonplaats, gemeente, wijk, buurt, kadastrale percelen en coördinaten.

Aanroepen

GET /v1/bag/adressen?q={zoekterm}&rows=8&start=0    // zoeken met paging
GET /v1/bag/suggest?q={fragment}&rows=6              // type-ahead
GET /v1/bag/lookup?id={object-id}                     // object per id

Responsvelden (per resultaat)

Bron en brondocumentatie

Bron: PDOK Locatieserver (BAG). Licentie CC0 1.0 — vrij hergebruik, geen attributie verplicht.
Onderliggende documentatie: pdok.nl · Locatieserver · Kadaster BAG API

Kerncijfers wijken en buurten per regio: inwoners, huishoudens, woningvoorraad, gemiddelde WOZ-waarde, inkomen en leeftijdsopbouw. Regiocodes volgen uit de BAG-API.

Aanroepen

GET /v1/cbs/kerncijfers?regio={code}&jaar=2025     // profiel per regio (en jaar)
GET /v1/cbs/regios?binnen={code}&niveau=wijk     // alle regio's binnen een gebied

Voorbeeld: /v1/cbs/regios?binnen=GM0363&niveau=wijk levert alle 110 Amsterdamse wijken met codes — die elk direct in kerncijfers te gebruiken zijn.

Responsvelden

Beschikbare kerncijfers: inwoners, huishoudens, woningvoorraad, gemiddelde_woz_waarde (€×1000), inkomen_per_ontvanger, inkomen_per_inwoner, aandeel_laagste_inkomens, aandeel_hoogste_inkomens, inwoners_0_tot_15, inwoners_65_plus.

Bron en brondocumentatie

Bron: CBS StatLine, tabel "Kerncijfers wijken en buurten" (jaarlijks wisselend tabel-id; het actuele jaar staat in bronnen[].tabel). Licentie CC BY 4.0 — attributie "CBS, Den Haag" is verplicht en wordt in elk antwoord meegeleverd.
Onderliggende documentatie: cbs.nl · Open Data · tabel-informatie (86165NED)

Alle kadastrale percelen rond een punt: aanduiding (gemeente, sectie, nummer), oppervlak, grootte-soort, historiestatus en geometrie. Combineerbaar met de BAG-API (coördinaten) of de percelen uit een adresrespons.

Aanroepen

GET /v1/kadaster/percelen?lon={l}&lat={b}&radius=50                 // kadastrale percelen
GET /v1/kadaster/grenzen?lon={l}&lat={b}&radius=50                  // perceelsgrenzen (lijnen)
GET /v1/kadaster/bebouwing?lon={l}&lat={b}&radius=50                // gebouwvoetprints (BAG-koppeling)
GET /v1/kadaster/openbareruimtenamen?lon={l}&lat={b}&radius=50      // straatnamen
GET /v1/kadaster/nummeraanduidingreeksen?lon={l}&lat={b}&radius=50  // huisnummerreeksen
GET /v1/kadaster/percelen/{id}                                       // één perceel per id

Alle vijf de kaartlagen delen hetzelfde aanroeppatroon:

Responsvelden per laag

Elk object bevat bovendien objecttype, identificatie en geometrie_wgs84 (GeoJSON). De bag_pand_id- en bag_openbare_ruimte_id-velden sluiten direct aan op de BAG-API.

Bron en brondocumentatie

Bron: PDOK OGC API — Kadastrale kaart (alle vijf de collecties). Licentie CC0 1.0.
Onderliggende documentatie: pdok.nl · Kadastrale kaart OGC API · endpoint-verkenner

Actuele luchtkwaliteitsmetingen per meetstation: stof, waarde, eenheid en meettijdstip. Gebruik de stationslijst om een stationnummer te vinden.

Aanroepen

GET /v1/luchtmeetnet/metingen?station={nr}&formule=PM10&van=…&tot=…   // metingen (+filters)
GET /v1/luchtmeetnet/stations?zoek={filter}&pagina=1                   // stationlijst

Het toegepaste filter wordt in de respons herhaald onder data.filter, zodat antwoorden altijd zelfbeschrijvend zijn.

Responsvelden (per meting)

Bron en brondocumentatie

Bron: Luchtmeetnet (RIVM en samenwerkende GGD'en). Attributie "Luchtmeetnet" bij hergebruik.
Onderliggende documentatie: api-docs.luchtmeetnet.nl · luchtmeetnet.nl

Voertuiggegevens uit de open Basisregistratie Voertuigen van de RDW: per kenteken (exact) of per merk (zoekresultaat).

Aanroepen

GET /v1/rdw/voertuigen?kenteken=XS005T          // per kenteken
GET /v1/rdw/voertuigen?merk=TESLA&rows=5     // per merk

Responsvelden (per voertuig)

kenteken, voertuigsoort, merk, handelsbenaming, eerste_kleur, aantal_zitplaatsen, aantal_deuren, aantal_wielen, lengte_mm, breedte_mm, massa_rijklaar_kg, catalogusprijs_eur, datum_eerste_toelating (ISO), datum_eerste_afgifte_nl, wam_verzekerd, trekker. De bron levert ~52 velden als ruwe strings; wij leveren de curate set met getallen als getallen en datums als ISO-8601.

Bron en brondocumentatie

Bron: RDW Open Data (Socrata), dataset m9d7-ebf2. Licentie CC0 1.0.
Onderliggende documentatie: opendata.rdw.nl

Het landelijke rijksmonumentenregister, met per monument o.a. adres en BAG-koppelingen (heeft_pand, heeft_verblijfsobject) — direct te combineren met de BAG-API.

Aanroepen

GET /v1/rce/monumenten?rijksmonumentnummer=518313        // per nummer
GET /v1/rce/monumenten?postcode=1012JS&straat=Dam      // per adres
GET /v1/rce/monumenten?woonplaatsnaam=Amsterdam          // per plaats

De bron levert JSON-LD met wisselende velden per treffer; wij vlakken die af naar stabiele snake_case-velden. De veldenset per monument kan daarom per treffer verschillen (null = niet geregistreerd). Bronparameters gemeenteCode en provinciecode leveren in de praktijk lege responses en worden daarom niet aangeboden.

Bron en brondocumentatie

Bron: RCE Linked Data API (Rijksmonumentenregister). Licentie CC0 1.0.
Onderliggende documentatie: cultureelerfgoed.github.io/API · monumentenregister.cultureelerfgoed.nl

De meta-bron: de landelijke catalogus met 20.300+ open datasets van honderden Nederlandse instanties. Vind per onderwerp welke data bestaat, bij wie, onder welke licentie — en of er een API-koppeling is.

Aanroepen

GET /v1/catalogus/datasets?q={zoekterm}&instantie=&rows=&start=   // zoeken
GET /v1/catalogus/datasets/{id}                                        // detail per slug/uuid
GET /v1/catalogus/instanties                                           // publicerende instanties
GET /v1/datasets/{id}/data?resource=0&rijen=50                      // ruwe weergave (universeel)
GET /v1/datasets/{id}/query?waar=kolom=waarde&velden=a,b&sorteer=k // QUERY-BARE API (normale calls)

Responsvelden (per dataset)

Bron en brondocumentatie

Bron: data.overheid.nl (Koop Overheid), CKAN API v3. Licentie CC0.
Onderliggende documentatie: data.overheid.nl · API · CKAN API-documentatie

Alle API's zijn direct als tools beschikbaar via het Model Context Protocol. Elke MCP-client (Claude Desktop, Cursor, uw eigen chatbot) kan ze zo aanspreken — de tools dragen Nederlandse beschrijvingen en JSON-Schema's waarmee een LLM zelfstandig de juiste tool kiest en parameters invult.

Transport 1 — streamable HTTP (aanbevolen)

POST /mcp        Content-Type: application/json   (JSON-RPC 2.0)

{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": { "protocolVersion": "2025-06-18" } }

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "cbs_kerncijfers", "arguments": { "regio": "WK0363AE" } } }

Clientconfiguratie (bijv. Claude Desktop / Cursor / eigen agent):

{
  "mcpServers": {
    "nederland-cloud": {
      "url": "https://nederland.cloud/mcp"
    }
  }
}

Transport 2 — stdio (lokaal)

{
  "mcpServers": {
    "nederland-cloud": {
      "command": "python3",
      "args": ["/pad/naar/mcp_server.py"]
    }
  }
}

Beschikbare tools

Toolantwoorden bevatten dezelfde genormaliseerde JSON als de HTTP-API's, inclusief de bronnen[]-herkomst. Fouten (bijv. ontbrekende parameter) keren terug als isError: true met een leesbare melding — zodat een LLM zichzelf kan corrigeren.

llms.txt

Voor LLM's zonder MCP: GET /llms.txt serveert een compact markdown-overzicht van alle endpoints, parameters en het responsformaat — direct in te laden als context. De OpenAPI-specificatie is eveneens beschikbaar voor frameworks die tools uit een specificatie genereren.