Hoe werkt een Postcode API technisch? [Complete Gids]

Een postcode-API klinkt eenvoudig — je stuurt een postcode en huisnummer, en je krijgt een adres terug. Maar er gaat heel wat techniek achter schuil. Deze gids legt alles uit: van de onderliggende database tot correcte foutafhandeling.

Wat is een Postcode API?

Een postcode-API is een webservice die een postcode (en optioneel huisnummer) omzet naar een volledig, gestructureerd adres. Het resultaat bevat doorgaans straatnaam, huisnummer, plaatsnaam, gemeente, provincie en GPS-coördinaten.

Hoe werkt een adresopzoeking technisch?

1. Input

De aanroep bevat minimaal:

• postalcode — de postcode (bijv. 1092CX)
• number — het huisnummer (bijv. 12)
• Optioneel: numberAddition — huisnummertoevoeging (bijv. A)

2. Zoeken in de database

De API zoekt in een actuele kopie van de Basisregistratie Adressen en Gebouwen (BAG) — de officiële Nederlandse adressenregistratie. Deze database bevat alle officieel geregistreerde adressen in Nederland en wordt maandelijks bijgewerkt vanuit de rijksoverheid.

3. Response

{
  "street": "Linnaeusstraat",
  "number": 12,
  "numberAddition": "",
  "postalcode": "1092CX",
  "city": "Amsterdam",
  "municipality": "Amsterdam",
  "province": "Noord-Holland",
  "streetShort": "Linnaeusstraat",
  "location": {
    "coordinates": {
      "latitude": 52.3586,
      "longitude": 4.9254
    }
  }
}

Verschillende typen API-aanvragen

Snelheid en betrouwbaarheid

Een goede postcode-API beantwoordt verzoeken binnen 300 milliseconden. ApiCheck haalt gemiddeld minder dan 100ms. Dat is snel genoeg voor live gebruik in formulieren, zonder merkbare vertraging voor de gebruiker.

Voor hogere volumes kun je responses cachen. Let op: adressen worden maandelijks bijgewerkt in de BAG. Een cache-levensduur van 7–30 dagen is in de meeste gevallen prima.

Foutafhandeling

Een robuuste integratie houdt rekening met foutscenario's:

• 404 Not Found: Postcode + huisnummer bestaat niet. Toon een melding aan de gebruiker.
• 422 Unprocessable: Ongeldige input (bijv. verkeerd postcode-formaat).
• 429 Too Many Requests: Je hebt je rate limit bereikt.
• 503 Service Unavailable: Tijdelijke storing. Implementeer retry-logica met exponential backoff.

Voorbeeld implementatie in PHP

$response = Http::withHeaders([
    'X-Api-Key' => config('services.apicheck.key'),
])->get('https://api.apicheck.nl/lookup/v1/address/nl', [
    'postalcode' => '1092CX',
    'number' => 12,
]);

if ($response->ok()) {
    $address = $response->json();
    echo $address['street']; // Linnaeusstraat
}

Voorbeeld implementatie in JavaScript

const response = await fetch(
  '/api/validate/address?postalcode=1092CX&number=12'
);
const address = await response.json();
document.getElementById('street').value = address.street;
document.getElementById('city').value = address.city;

Beveiliging

Nooit de API direct vanuit de browser aanroepen met je echte API-sleutel zichtbaar in de JavaScript-code. Gebruik altijd een server-side proxy die:

1. De aanroep accepteert van de browser
2. Je echte API-sleutel toevoegt server-side
3. De respons terugstuurt naar de browser

ApiCheck's eigen demo-implementatie werkt ook zo — zie routes/api.php voor een voorbeeld.

Veelgemaakte fouten

1. API-sleutel in frontend JavaScript — nooit doen
2. Geen fallback bij 404 — gebruiker zit vast als het adres niet bestaat
3. Cache te lang bewaren — adressen veranderen soms bij hernummering
4. Geen rate limiting — sommige gebruikers spammen formulieren

Conclusie

Een postcode-API is conceptueel eenvoudig maar vereist zorgvuldige implementatie voor productiegebruik. Met een server-side proxy, correcte foutafhandeling en slimme caching bouw je een robuuste integratie die jarenlang meegaat.