How Does a Postcode API Work Technically? [Complete Guide]

A postcode API sounds simple — you send a postal code and house number, and you get an address back. But there is a lot of technology behind it. This guide explains everything: from the underlying database to correct error handling.

What Is a Postcode API?

A postcode API is a web service that converts a postal code (and optionally a house number) into a complete, structured address. The result typically contains the street name, house number, city, municipality, province, and GPS coordinates.

How Does an Address Lookup Work Technically?

1. Input

The call contains at minimum:

• postalcode — the postal code (e.g. 1092CX)
• number — the house number (e.g. 12)
• Optionally: numberAddition — house number addition (e.g. A)

2. Database Search

The API searches in a current copy of the Basisregistratie Adressen en Gebouwen (BAG) — the official Dutch address registry. This database contains all officially registered addresses in the Netherlands and is updated monthly from government sources.

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
    }
  }
}

Different Types of API Requests

Speed and Reliability

A good postcode API responds to requests within 300 milliseconds. ApiCheck averages less than 100ms. That is fast enough for live use in forms without any noticeable delay for the user.

For higher volumes you can cache responses. Note: addresses are updated monthly in the BAG. A cache lifetime of 7–30 days is fine in most cases.

Error Handling

A robust integration accounts for error scenarios:

• 404 Not Found: Postal code + house number does not exist. Show a message to the user.
• 422 Unprocessable: Invalid input (e.g. wrong postal code format).
• 429 Too Many Requests: You have reached your rate limit.
• 503 Service Unavailable: Temporary outage. Implement retry logic with exponential backoff.

Example Implementation 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
}

Example Implementation 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;

Security

Never call the API directly from the browser with your real API key visible in the JavaScript code. Always use a server-side proxy that:

1. Accepts the call from the browser
2. Adds your real API key server-side
3. Sends the response back to the browser

ApiCheck's own demo implementation works this way too — see routes/api.php for an example.

Common Mistakes

1. API key in frontend JavaScript — never do this
2. No fallback on 404 — the user gets stuck if the address does not exist
3. Caching too long — addresses sometimes change during renumbering
4. No rate limiting — some users spam forms

Conclusion

A postcode API is conceptually simple but requires careful implementation for production use. With a server-side proxy, correct error handling, and smart caching, you build a robust integration that will last for years.