Inloggen

DEVELOPER DOCUMENTATIE

API documentatie

Alle endpoints, parameters, foutcodes en codevoorbeelden overzichtelijk bij elkaar voor een snelle integratie.

Code generator Live demo

SNEL STARTEN

Koppel de API in minuten

Gebruik je API-key via de Authorization Bearer header en bouw direct met voorbeelden voor PHP, cURL, Python, Node.js en meer.

Snel starten Authenticatie

Snel Starten

De basis-URL van de API is: 

https://api.postcodeconnect.nl

Een standaardrequest bestaat uit een endpoint, parameters en je API-key in een header. 

curl "https://api.postcodeconnect.nl/lookupzip?postcode=2283GM&housenumber=2" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer JOUW_API_KEY"

Gebruik altijd HTTPS. Responses zijn JSON met meestal een veld ok, plus items of item.

Authenticatie

Elke API-aanroep moet een API-key meesturen via de HTTP-header Authorization met het Bearer schema. Een API-key via de URL, zoals ?key=... of ?api_key=..., wordt niet gebruikt en kan op de server worden geblokkeerd. Zet je key dus nooit in het adres. 

Authorization: Bearer JOUW_API_KEY

Bewaar API-keys alleen server-side. Zet ze niet rechtstreeks in browser-JavaScript, mobiele apps of openbare repositories.

Algemene Werking

HTTP-methodes

De meeste endpoints zijn GET. Alleen polygonsearch is bedoeld voor POST met een JSON body.

Postcodeformaat

Postcodes mogen met of zonder spatie worden gestuurd. De API normaliseert bijvoorbeeld 2283 NB en 2283GM.

Paginatie

Endpoints die meerdere resultaten teruggeven tonen maximaal 250 resultaten per request, tenzij bij het endpoint een lagere limiet staat. Een request telt altijd als 1 call, ook als er geen resultaat wordt gevonden of als er meerdere resultaten in de response staan.

Als er meer resultaten beschikbaar zijn, laat de API dat zien met velden zoals total, has_more, next_offset of last. Je haalt extra resultaten op door een nieuwe request te doen met de volgende offset of cursor. Die vervolgrequest telt opnieuw als 1 call. 

GET /lookupcity?city=Rijswijk&limit=250&offset=0

{
  "ok": true,
  "total": 6421,
  "items": [ ... ],
  "limit": 250,
  "offset": 0,
  "has_more": true,
  "next_offset": 250
}

De volgende pagina vraag je daarna zo op: 

GET /lookupcity?city=Rijswijk&limit=250&offset=250

Cacheheaders

Sommige endpoints sturen X-Cache: HIT of X-Cache: MISS. Dit is informatief: HIT betekent dat de response uit de servercache kwam.

Endpoint: lookupzip

Zoek adressen op basis van postcode. Met huisnummer krijg je een exact adres. Zonder huisnummer krijg je een lijst met adressen binnen de postcode. 

GET /lookupzip?postcode={postcode}&housenumber={huisnummer}

Parameters

  • postcode verplicht. Alias: pc, zip.
  • housenumber optioneel. Alias: hn, number, nr.
  • houseletter optioneel.
  • addition optioneel.
  • includeWijken optioneel. Gebruik 0 of false om wijk/buurtinformatie uit te zetten.
  • limit alleen bij postcode-zonder-huisnummer. Maximaal 250 resultaten per request.
  • offset alleen bij postcode-zonder-huisnummer.

Exact adres

curl "https://api.postcodeconnect.nl/lookupzip?postcode=2283GM&housenumber=2" \
  -H "Authorization: Bearer JOUW_API_KEY"
{
  "ok": true,
  "total": 1,
  "item": {
    "straatnaam": "Voorbeeldstraat",
    "huisnummer": 2,
    "huisletter": "",
    "toevoeging": "",
    "postcode": "2283GM",
    "woonplaats": "Rijswijk",
    "gemeente": "Rijswijk",
    "buurt": "Voorbeeldbuurt",
    "wijk": "Voorbeeldwijk",
    "latitude": 52.000000,
    "longitude": 4.000000
  },
  "query_ms": 4
}

Alle adressen binnen een postcode

GET /lookupzip?postcode=2283GM&limit=25&offset=0

De response bevat dan items, total, has_more en next_offset.

Als has_more true is, gebruik je next_offset in een volgende request om de volgende pagina op te halen. Elke pagina is een nieuwe request en kost dus 1 call.

Endpoint: getaddressbylatlong

Zoek het dichtstbijzijnde adres bij een latitude/longitude-coordinaat. 

GET /getaddressbylatlong?lat={latitude}&long={longitude}

Parameters

  • lat verplicht. Latitude tussen -90 en 90.
  • long verplicht. Aliassen: lon, lng. Longitude tussen -180 en 180.
curl "https://api.postcodeconnect.nl/getaddressbylatlong?lat=52.0481&long=4.3300" \
  -H "Authorization: Bearer JOUW_API_KEY"
{
  "ok": true,
  "total": 1,
  "item": {
    "straatnaam": "Voorbeeldstraat",
    "huisnummer": 2,
    "postcode": "2283GM",
    "woonplaats": "Rijswijk",
    "distance_m": 12.34
  }
}

Autocomplete Endpoints

getstreetsautocomplete

Zoek straatnamen en woonplaatsen op basis van een beginnende zoekterm. Bij meerdere woorden wordt het laatste woord ook als plaatsnaam gebruikt. 

GET /getstreetsautocomplete?q={zoekterm}&limit={n}
  • q verplicht, minimaal 2 tekens.
  • limit optioneel, standaard 50, maximaal 200.
{
  "ok": true,
  "items": [
    { "straatnaam": "Generaal Spoorlaan", "woonplaats": "Rijswijk" }
  ]
}

gethousenumbers

Haal huisnummers op voor een straat en woonplaats. Handig na straat-autocomplete. 

GET /gethousenumbers?straat={straatnaam}&plaats={woonplaats}&nr={prefix}&last={laatste}&limit={n}
  • straat verplicht.
  • plaats verplicht.
  • nr optioneel, start/prefix voor huisnummer.
  • last optioneel, voor vervolgpaginatie op huisnummer.
  • limit optioneel, standaard 50, maximaal 200.
{
  "ok": true,
  "items": ["1", "2", "2A", "4"],
  "last": 4,
  "has_more": false
}

Bij has_more: true gebruik je de waarde uit last als nieuwe last-parameter om de volgende reeks huisnummers op te halen. Die vervolgrequest telt als 1 extra call.

getaddressbystreetnumber

Zoek een adres op met straatnaam, woonplaats en huisnummertekst. 

GET /getaddressbystreetnumber?straat={straatnaam}&plaats={woonplaats}&nr={nummer}

nr mag bijvoorbeeld 12, 12A of 12 bis zijn.

Endpoint: getpostcodepolygon

Maakt een benaderde polygon op basis van adrespunten binnen een volledige postcode of viercijferig postcodegebied. 

GET /getpostcodepolygon?postcode={postcode}&format=geojson

Alias: /postcodepolygon.

Parameters

  • postcode verplicht. Gebruik 2283GM of vier cijfers zoals 2283.
  • format optioneel: geojson, wkt of both. Standaard geojson.
  • bufferMeters optioneel, minimaal 5, maximaal 100. Standaard 8.
  • clusterMeters optioneel, minimaal 1, maximaal 250. Standaard 50.
  • includeAddresses optioneel. Gebruik 1 of true om adrespunten mee terug te geven.
curl "https://api.postcodeconnect.nl/getpostcodepolygon?postcode=2283GM&format=both" \
  -H "Authorization: Bearer JOUW_API_KEY"

De response bevat onder andere feature_collection, geometry_wkt, bounds, center en address_count, afhankelijk van format.

Endpoint: getdistance

Berekent de hemelsbrede afstand tussen twee adressen. 

GET /getdistance?postcode_from=...&housenumber_from=...&postcode_to=...&housenumber_to=...

Alias: /distancebetweenaddresses.

Parameters

  • Van-adres: postcode_from, housenumber_from, optioneel houseletter_from, addition_from.
  • Naar-adres: postcode_to, housenumber_to, optioneel houseletter_to, addition_to.
  • Aliassen zijn beschikbaar, zoals pc1, hn1, pc2, hn2.
{
  "ok": true,
  "from": { "postcode": "2283GM", "huisnummer": 2 },
  "to": { "postcode": "2511BT", "huisnummer": 1 },
  "distance": {
    "meters": 5123.45,
    "kilometers": 5.123,
    "type": "straight_line"
  }
}

Plaats Endpoints

lookupcity

Geeft adressen terug binnen een woonplaats, eventueel gefilterd op buurt. 

GET /lookupcity?city={woonplaats}&buurt={buurt}&limit=250&offset=0

Alias: /lookupwoonplaats.

  • city verplicht. Alias: woonplaats.
  • buurt optioneel. Alias: neighborhood.
  • limit optioneel, maximaal 250.
  • offset optioneel.

Gebruik has_more en next_offset om extra pagina's op te halen. Elke pagina kost 1 call.

getcities

Geeft woonplaatsen terug, optioneel gefilterd op begin van de naam. 

GET /getcities?q={zoekterm}&limit=250&offset=0

Alias: /getwoonplaatsen.

  • q optioneel.
  • limit optioneel, maximaal 250.
  • offset optioneel.

Gebruik has_more en next_offset voor de volgende pagina.

Endpoint: lookupareas

Geeft buurten/wijken binnen een woonplaats terug, inclusief polygon in WKT. 

GET /lookupareas?city={woonplaats}&buurt={buurt}&limit=250&offset=0

Alias: /lookupwijken.

  • city verplicht. Alias: woonplaats.
  • buurt optioneel. Aliassen: neighborhood, bu_naam.
  • limit optioneel, maximaal 250.
  • offset optioneel.

Bij meerdere buurten/wijken geeft de response total, has_more en next_offset terug. Gebruik next_offset voor de volgende pagina. 

{
  "ok": true,
  "total": 2,
  "items": [
    {
      "id": 123,
      "city": "Rijswijk",
      "buurt": "Voorbeeldbuurt",
      "wijk": "Voorbeeldwijk",
      "geometry_wkt": "POLYGON((...))"
    }
  ]
}

Endpoint: polygonsearch

Zoekt adressen binnen een GeoJSON Polygon. Dit endpoint gebruikt POST met JSON. 

POST /polygonsearch
Content-Type: application/json
Authorization: Bearer JOUW_API_KEY

Belangrijke limieten

  • Alleen Polygon wordt ondersteund.
  • Maximaal 5000 polygonpunten.
  • Maximale bounding box: 5 km breed en 5 km hoog.
  • Maximale oppervlakte: 25 km².
  • Maximaal 250 resultaten per call.

Body parameters

  • polygon verplicht. GeoJSON Geometry of Feature met type: "Polygon".
  • limit optioneel, maximaal 250.
  • offset optioneel.
  • after_id optioneel voor vervolgpagina's zonder sortering.
  • countOnly optioneel. Geeft alleen aantal terug.
  • approx optioneel. Snellere bounding-box modus.
  • onlyPostcodes optioneel. Geeft alleen postcodes terug.
  • distinct optioneel. Probeert dubbele rijen te voorkomen.
  • sort optioneel. Sorteert op postcode/straat/huisnummer.
  • fields optioneel. Geldige velden: postcode, straatnaam, huisnummer, huisletter, toevoeging, woonplaats, gemeenteCode, buurt, wijk, latitude, longitude.
{
  "polygon": {
    "type": "Polygon",
    "coordinates": [[
      [4.3300, 52.0400],
      [4.3500, 52.0400],
      [4.3500, 52.0550],
      [4.3300, 52.0550],
      [4.3300, 52.0400]
    ]]
  },
  "limit": 100,
  "fields": ["postcode", "straatnaam", "huisnummer", "woonplaats", "latitude", "longitude"]
}
{
  "ok": true,
  "mode": "results",
  "items": [],
  "fields": ["postcode", "straatnaam", "huisnummer", "woonplaats"],
  "limit": 100,
  "has_more": false,
  "next_offset": null
}

Bij has_more: true kun je verder bladeren met next_offset. Zonder sortering kan ook next_after_id beschikbaar zijn; stuur die waarde dan als after_id mee voor de volgende pagina. Elke vervolgpagina kost 1 call.

Foutcodes

Bij fouten geeft de API JSON terug met ok: false en een error-code.

  • api_key_required - API-key ontbreekt in de Authorization: Bearer header.
  • invalid_api_key - API-key is onbekend of niet actief.
  • insufficient_scope - API-key heeft geen toegang tot dit endpoint.
  • rate_or_quota_exceeded - RPS of maandquota overschreden.
  • invalid_postcode - Postcodeformaat klopt niet.
  • invalid_housenumber - Huisnummer ontbreekt of is ongeldig.
  • invalid_coordinates - Latitude/longitude ontbreken of liggen buiten bereik.
  • not_found of address_not_found - Geen resultaat gevonden.
  • missing_city - Woonplaats ontbreekt.
  • missing_polygon - Polygon ontbreekt.
  • polygon_too_large - Polygon is groter dan 5 x 5 km of 25 km².
  • only_polygon_supported - Alleen GeoJSON Polygon wordt ondersteund.

Codevoorbeelden

PHP cURL

<?php
$url = 'https://api.postcodeconnect.nl/lookupzip?postcode=2283GM&housenumber=2';
$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Accept: application/json',
    'Authorization: Bearer JOUW_API_KEY',
  ],
]);

$response = curl_exec($ch);
if ($response === false) {
  throw new RuntimeException(curl_error($ch));
}

$data = json_decode($response, true);
var_dump($data);

JavaScript via je eigen backend

Gebruik de API-key niet rechtstreeks in frontend JavaScript. Maak een eigen server-endpoint dat de request doorstuurt. 

async function lookupAddress(postcode, housenumber) {
  const res = await fetch('/jouw-backend/lookup-address', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ postcode, housenumber })
  });

  if (!res.ok) {
    throw new Error('Adres kon niet worden opgehaald');
  }

      return await res.json();
}

Code Generator

Kies een endpoint en taal. Vul de parameters in en kopieer direct een werkend voorbeeld. De API-key wordt altijd als Authorization: Bearer header gebruikt.