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 GM en 2283GM.

Paginatie

Endpoints die meerdere resultaten teruggeven tonen maximaal 250 resultaten per request. 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 adres terug. Als er meerdere varianten bestaan voor hetzelfde huisnummer, bijvoorbeeld huisletter of toevoeging, bevat de response naast item ook items. Zonder huisnummer krijg je een lijst met adressen binnen de postcode. Bij 2 t/m 4 cijfers geeft de endpoint postcodegebied-suggesties terug voor autocomplete. Bij 4 cijfers plus 1 letter, zoals 2283N, geeft de endpoint volledige postcode-suggesties terug.

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

Parameters

• postcode verplicht. Gebruik 2283GM, 2 t/m 4 cijfers zoals 22 of 2283 voor postcodegebied-suggesties, of 4 cijfers plus 1 letter zoals 2283N voor volledige postcode-suggesties. Alias: pc, zip.
• housenumber optioneel. Alias: hn, number, nr. Mag ook compact worden gebruikt, zoals 1A of 1A 2, wanneer je eigen backend dit zo doorstuurt.
• houseletter optioneel.
• addition optioneel. Gebruik dit voor de exacte toevoeging, bijvoorbeeld 2 in 1A 2.
• includeWijken optioneel. Gebruik 0 of false om wijk/buurtinformatie uit te zetten.
• limit bij lijsten en varianten. Maximaal 250 resultaten per request.
• offset alleen bij postcode-zonder-huisnummer.

Adres of adresvarianten

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

Bij een unieke combinatie bevat de response vooral item. Als de combinatie meerdere adressen kan betekenen, bijvoorbeeld postcode=2517AA&housenumber=1&houseletter=A, dan bevat de response ook items, variant_count en has_variants. item blijft aanwezig als eerste/beste match voor backwards compatibility.

{
  "ok": true,
  "total": 1,
  "item": {
    "straatnaam": "Voorbeeldstraat",
    "huisnummer": 2,
    "huisletter": "",
    "toevoeging": "",
    "postcode": "2283GM",
    "woonplaats": "Rijswijk",
    "provincie": "Zuid-Holland",
    "gemeente": "Rijswijk",
    "buurt": "Voorbeeldbuurt",
    "wijk": "Voorbeeldwijk",
    "latitude": 52.000000,
    "longitude": 4.000000
  },
  "query_ms": 4
}

Huisletter en toevoeging

GET /lookupzip?postcode=2517AA&housenumber=1&houseletter=A

{
  "ok": true,
  "total": 8,
  "item": {
    "straatnaam": "Laan van Meerdervoort",
    "huisnummer": 1,
    "huisletter": "A",
    "toevoeging": "",
    "postcode": "2517AA",
    "woonplaats": "'s-Gravenhage"
  },
  "items": [
    { "huisnummer": 1, "huisletter": "A", "toevoeging": "" },
    { "huisnummer": 1, "huisletter": "A", "toevoeging": "1" },
    { "huisnummer": 1, "huisletter": "A", "toevoeging": "2" }
  ],
  "variant_count": 8,
  "has_variants": true
}

Wil je exact een toevoeging selecteren, geef dan ook addition mee:

GET /lookupzip?postcode=2517AA&housenumber=1&houseletter=A&addition=2

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.

Postcodegebied autocomplete

GET /lookupzip?postcode=22&limit=10&autocomplete=1

{
  "ok": true,
  "type": "postcode_prefix",
  "query": "22",
  "items": [
    { "postcode": "2201", "woonplaats": "Noordwijk", "address_count": 7597 },
    { "postcode": "2202", "woonplaats": "Noordwijk", "address_count": 5668 }
  ]
}

Viercijferige postcode autocomplete

GET /lookupzip?postcode=7742&limit=6&autocomplete=1

{
  "ok": true,
  "type": "postcode_prefix",
  "query": "7742",
  "items": [
    { "postcode": "7742", "woonplaats": "Coevorden", "address_count": 3088 },
    { "postcode": "7742AB", "woonplaats": "Coevorden", "address_count": 9 },
    { "postcode": "7742AC", "woonplaats": "Coevorden", "address_count": 28 }
  ]
}

Volledige postcode autocomplete

GET /lookupzip?postcode=2283N&limit=10&autocomplete=1

{
  "ok": true,
  "type": "postcode_letter_prefix",
  "query": "2283N",
  "items": [
    { "postcode": "2283NA", "woonplaats": "Rijswijk", "address_count": 1 },
    { "postcode": "2283GM", "woonplaats": "Rijswijk", "address_count": 7 }
  ]
}

Huisnummer autocomplete binnen postcode

GET /lookupzip?postcode=2283GM&housenumber=2&limit=10&autocomplete=1

{
  "ok": true,
  "type": "postcode_housenumber_prefix",
  "query": "2283GM",
  "housenumber_prefix": "3",
  "items": [
    { "straatnaam": "Generaal Spoorlaan", "huisnummer": 2, "postcode": "2283GM", "woonplaats": "Rijswijk" }
  ]
}

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",
    "provincie": "Zuid-Holland",
    "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 250.

{
  "ok": true,
  "items": [
    { "straatnaam": "Generaal Spoorlaan", "woonplaats": "Rijswijk" }
  ]
}

gethousenumbers

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

Gebruik voor een adres-autocomplete flow meestal deze volgorde: getstreetsautocomplete voor straat + plaats, daarna gethousenumbers met last-paginatie, en tot slot getaddressbystreetnumber voor het gekozen huisnummer.

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 250.

{
  "ok": true,
  "items": ["1", "1A", "1A 1", "1A 2", "1B", "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.

De response is natuurlijk gesorteerd op huisnummer, huisletter en toevoeging. Daardoor staan varianten zoals 1A 1, 1A 2 en 1A 3 direct onder 1A.

Let op: items zijn tekstwaarden. Sorteer ze in je frontend op huisnummer, huisletter en toevoeging wanneer je een nette autocomplete wilt tonen. Dan staat 1A 1 direct onder 1A in plaats van pas na 1Y.

getaddressbystreetnumber

Zoek een adres op met straatnaam, woonplaats en huisnummertekst. Net als bij lookupzip kan de response meerdere varianten bevatten wanneer de invoer nog niet volledig exact is.

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

nr mag bijvoorbeeld 12, 12A, 12A 2 of 12 bis zijn. Bij nr=12A krijg je ook toevoegingen onder 12A terug in items. Bij nr=12A 2 zoekt de API exact op toevoeging 2.

{
  "ok": true,
  "total": 3,
  "item": { "huisnummer": 12, "huisletter": "A", "toevoeging": "" },
  "items": [
    { "huisnummer": 12, "huisletter": "A", "toevoeging": "" },
    { "huisnummer": 12, "huisletter": "A", "toevoeging": "1" },
    { "huisnummer": 12, "huisletter": "A", "toevoeging": "2" }
  ],
  "variant_count": 3,
  "has_variants": true
}

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.

Dit endpoint is beschikbaar in de betaalde pakketten en zit niet in het gratis Starter pakket.

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 oppervlakte: 40 km². Lengte en breedte maken niet uit zolang de totale oppervlakte binnen deze limiet blijft.
• 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, provincie, statnaam, 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", "provincie", "latitude", "longitude"]
}

{
  "ok": true,
  "mode": "results",
  "items": [],
  "fields": ["postcode", "straatnaam", "huisnummer", "woonplaats", "provincie"],
  "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 40 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');
  }

  const data = await res.json();

  if (data.has_variants) {
    // Toon data.items in je UI en laat de gebruiker de juiste toevoeging kiezen.
    return data.items;
  }

  return data.item;
}

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.