Ga naar hoofdinhoud

Concepten

Begrijp de structuur van BAG-data en de gebruikte coordinatenstelsels.

// BAG_MODELBAG Datamodel
BAG DatamodelDe Basisregistratie Adressen en Gebouwen

De BAG is de officiële Nederlandse registratie van alle adressen en gebouwen. De data is gestructureerd in acht objecttypes.

Gemeente

(Municipality)

Een gemeente, geïdentificeerd door haar 4-cijferige CBS-code; het hoogste bestuurlijke niveau in BAG

Voorbeeld: Amsterdam (CBS-code 0363), Rotterdam (0599)

Woonplaats

(City/Town)

Een officieel erkende plaats of stad in Nederland

Voorbeeld: 's-Gravenhage, Amsterdam, Rotterdam

Openbare Ruimte

(Public Space)

Een benoemde openbare ruimte zoals een straat, plein of park

Voorbeeld: Kneuterdijk, Damrak, Coolsingel

Nummeraanduiding

(Address Designation)

Een officieel adres met postcode en huisnummer

Voorbeeld: 2514GL 78, 1012AB 1

Verblijfsobject

(Dwelling/Premises)

Een eenheid voor verblijf zoals een woning of kantoor

Voorbeeld: Appartement, kantoor, winkel

Ligplaats

(Mooring Berth)

Een ligplaats voor woonschepen op het water; kan net als een verblijfsobject een adres dragen

Voorbeeld: Woonbootligplaatsen aan grachten

Standplaats

(Caravan Site)

Een standplaats op een kampeerterrein of vergelijkbaar terrein; kan net als een verblijfsobject een adres dragen

Voorbeeld: Vaste standplaatsen op kampeerterreinen

Pand

(Building)

Een fysiek gebouw met een eigen geometrie

Voorbeeld: Fysieke gebouwconstructie
// COORDINATESCoordinatenstelsels
CoordinatenstelselsGeografische posities in de API

De API levert coordinaten in twee stelsels: WGS84 voor wereldwijde compatibiliteit en Rijksdriehoek voor Nederlandse precisie.

WGS84

EPSG:4326

Wereldwijd GPS-stelsel, gebruikt door Google Maps en de meeste apps

Velden: latitude, longitude
Voorbeeld: 52.0815, 4.3118

Rijksdriehoek (RD)

EPSG:28992

Nederlands nationaal stelsel met hoge precisie voor Nederland

Velden: rd_x, rd_y
Voorbeeld: 81548, 454640
// GEOJSONGeoJSON Formaat
GeoJSON FormaatGeografische geometrie in JSON-formaat

Gebouwgeometrie wordt geretourneerd in GeoJSON-formaat, compatibel met de meeste mapping-bibliotheken.

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [4.3118, 52.0815]
  },
  "properties": {
    "nummeraanduiding_id": "0518200000123456",
    "full_address": "Kneuterdijk 78, 2514GL 's-Gravenhage",
    "postcode": "2514GL",
    "huisnummer": 78,
    "straatnaam": "Kneuterdijk",
    "woonplaats": "'s-Gravenhage",
    "source": "BAG"
  }
}
// POSTCODE_NORMPostcodenormalisatie
PostcodenormalisatieDe API accepteert postcodes in elke gangbare vorm en normaliseert ze tijdens verwerking.

Spaties worden weggehaald, letters worden in hoofdletters gezet. Je kunt 1234 ab, 1234AB of 1234ab doorgeven — ze worden allemaal omgezet naar de canonieke vorm van 6 tekens. Dit geldt voor postcode querystring-parameters, padsegmenten (/postcodes/{postcode}) en de request body van POST /export/addresses.

1234 AB   →  1234AB
1234ab    →  1234AB
1234 ab   →  1234AB
1234AB    →  1234AB
// FILTER_SYNTAXFilter- en sorteersyntax
Filter- en sorteersyntax
Lijst-endpoints ondersteunen de conventie filter[key]=value.

Filtersleutels staan per endpoint gedocumenteerd in de OpenAPI-specificatie. Typefouten en niet-ondersteunde sleutels worden afgewezen met HTTP 422 — ze worden niet stilzwijgend genegeerd. Sorteervelden zijn ook beperkt; gebruik - als prefix voor aflopend.

# Filter syntax — supported on /cities, /municipalities, /streets, /buildings/within-bbox
GET /api/v1/cities?filter[provincie_naam]=Noord-Holland
GET /api/v1/municipalities?filter[gemeente_naam]=Amsterdam
GET /api/v1/streets?filter[naam]=Damrak&filter[type]=Weg
GET /api/v1/buildings/within-bbox?north=...&filter[bouwjaar_min]=1900

# Ergonomic alias on /streets — `q` maps to filter[naam]
GET /api/v1/streets?q=Damrak

# Sort: prefix with - for descending
GET /api/v1/cities?sort=-naam

# Unknown filter[…] keys are rejected with 422 (catches typos like `provence`)
// RD_WGS84RD ↔ WGS84 invoer op geo-endpoints
RD ↔ WGS84 invoer op geo-endpointsBeide coordinatenstelsels worden geaccepteerd; de API converteert intern.

/addresses/nearby en /geocode/reverse accepteren WGS84 (lat/lng) of Nederlands RD (rd_x/rd_y) — kies wat aansluit op je bestaande data. Intern wordt alles omgezet naar WGS84 voor de ruimtelijke query.

RD-invoer wordt gevalideerd tegen het Nederlandse bereik: rd_x moet tussen 7000 en 300000 liggen, rd_y tussen 289000 en 629000. Coordinaten buiten dat bereik (een veelgemaakte fout met WGS84 in het RD-veld) worden afgewezen met een 422 in plaats van een leeg resultaat te geven.

// CORSCORS en browsersleutels
CORS en browsersleutelsDe API is standaard server-naar-server. Browserfrontends gebruiken een aparte browsersleutel.

Voor gebruik aan de serverzijde zijn geen CORS-headers nodig — de standaard Bearer-token werkt. Voor browserfrontends maak je een browsersleutel aan en voeg je de origins toe waarvan je wilt aanroepen aan de whitelist. De API echoot Access-Control-Allow-Origin alleen voor die origins; andere origins worden door de browser geblokkeerd. Herhaalde querystring-parameters gebruiken laatste-wint-gedrag (?postcode=A&postcode=B gebruikt B).

# Server-side: standard Bearer token, no CORS needed.
curl https://postcodetools.nl/api/v1/version \
  -H "Authorization: Bearer <api-key>"

# Browser frontend: use a Browser Key with a domain whitelist.
# The API echoes Access-Control-Allow-Origin only for whitelisted origins.
fetch("https://postcodetools.nl/api/v1/addresses/lookup?postcode=1012JS&number=1", {
  headers: { Authorization: "Bearer <api-key>" }
})