Documentatie
Laatst bijgewerkt: 8 juli 2026 · changelog
De postcode-service.nl API geeft je direct toegang tot ruim 36 miljoen adressen in Nederland, België en Frankrijk (plus Duitse postcodes) via de officiële registers — BAG, BeST en BAN. Stuur een postcode en huisnummer, ontvang een volledig adresobject terug.
Quickstart
Na registratie ontvang je direct een API key. Je eerste request:
curl -s \ -H "X-Api-Key: JOUW-API-KEY" \ "https://api.postcode-service.nl/v1/address/1021JT/19"
Authenticatie
Stuur je API key mee als HTTP header bij elk request. Je vindt je key in het dashboard.
X-Api-Key: JOUW-API-KEY
Endpoint
Alle requests zijn GET-requests zonder request body.
| Omgeving | Base URL |
|---|---|
| Productie | https://api.postcode-service.nl |
| Sandbox | https://sandbox.postcode-service.nl |
Parameters
| Parameter | Verplicht | Omschrijving |
|---|---|---|
| postcode | Ja | 4 cijfers + 2 letters, hoofdletterongevoelig, zonder spatie. Bv. 1021JT |
| huisnummer | Ja | Numeriek, optioneel gevolgd door huisletter. Bv. 19 of 19A |
| toevoeging | Nee | Optioneel derde segment. Alleen voor opmaak van het address veld. Bv. 1 of bis |
Response formaat
Succesvolle responses hebben HTTP status 200 en Content-Type: application/json.
{
"postcode": "1021JT",
"number": 19,
"letter": "A",
"addition": null,
"address": "Hamerstraat 19A",
"street": "Hamerstraat",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"location": {
"lat": 52.387855,
"lng": 4.917652
}
}
Velden
| Veld | Type | Omschrijving |
|---|---|---|
| postcode | string | Postcode in hoofdletters zonder spatie |
| number | integer | Huisnummer |
| letter | string|null | Huisletter zoals meegegeven in de URL, of null |
| addition | string|null | Toevoeging zoals meegegeven in de URL, of null |
| address | string | Volledig geformatteerd adres incl. huisletter en toevoeging |
| street | string | Straatnaam |
| city | string | Woonplaats |
| municipality | string | Gemeente |
| province | string | Provincie |
| location | object | Object met lat (breedtegraad) en lng (lengtegraad) |
Huisletter en toevoeging
De zoekopdracht vindt altijd het basisadres op postcode + huisnummer. Huisletter en toevoeging worden uitsluitend gebruikt voor de opmaak van address.
| URL | letter | addition | address |
|---|---|---|---|
| /v1/address/1021JT/19 | null | null | Hamerstraat 19 |
| /v1/address/1021JT/19A | A | null | Hamerstraat 19A |
| /v1/address/1021JT/19/1 | null | 1 | Hamerstraat 19-1 |
| /v1/address/1021JT/19A/bis | A | bis | Hamerstraat 19A-bis |
Foutcodes
Foutresponses hebben Content-Type: application/problem+json en een JSON body met een title veld.
| Status | Betekenis | Wanneer |
|---|---|---|
| 200 | OK | Adres gevonden |
| 400 | Bad Request | Ongeldig postcode- of huisnummerformaat |
| 401 | Unauthorized | Ongeldige of ontbrekende API key |
| 403 | Forbidden | Domein niet toegestaan voor deze API key |
| 404 | Not Found | Adres niet gevonden in de BAG-database |
| 429 | Too Many Requests | Rate limit overschreden (per seconde of per maand) |
Rate limits
Er zijn twee onafhankelijke limieten. Bij overschrijding ontvang je HTTP 429.
| Limiet | Omschrijving | Reset |
|---|---|---|
| Per seconde | Afhankelijk van je plan (5–25 calls/sec). Response bevat Retry-After: 1 | Na 1 seconde |
| Per maand | Het maandbudget van je abonnement | 1e van de maand |
Response headers
| Header | Omschrijving |
|---|---|
| X-RateLimit-Limit | Maandlimiet van je abonnement |
| X-RateLimit-Remaining | Resterende calls deze maand |
| X-RateLimit-Reset | Unix timestamp van de volgende reset |
Landen Bèta
Naast Nederland ondersteunen we adres-lookups in Frankrijk en België (huisnummer-niveau) en Duitsland (postcodeniveau) — telkens op basis van officiële, open registers. Meer landen volgen.
Adres opzoeken
De straat mag afgekort of zonder accenten zijn (av charles bohn matcht Avenue Charles Bohn). suffix is optioneel (bv. bis/ter).
GET /v1/fr/address?postcode=75011&street=rue+de+la+roquette&number=12
{
"country": "FR",
"postcode": "75011",
"number": 12,
"suffix": null,
"address": "Rue de la Roquette 12",
"street": "Rue de la Roquette",
"city": "Paris",
"region": "75",
"location": { "lat": 48.8543, "lng": 2.3767 }
}
Straten binnen een postcode
Voor checkout-flows: laat de klant eerst postcode invullen, toon dan de straten (max. 500), en valideer daarna met het adres-endpoint.
Duitsland: postcode → plaats
Duitsland heeft geen vrij huisnummer-register; wél valideren we de postcode en geven we plaats, Kreis en Bundesland terug (één postcode kan meerdere plaatsen dekken).
| Land | Code | Bron | Niveau |
|---|---|---|---|
| Nederland | nl | BAG (Kadaster) | Huisnummer — via /v1/address/… |
| Frankrijk | fr | Base Adresse Nationale | Huisnummer |
| België | be | BeST (BOSA) | Huisnummer — tweetalig (NL/FR) |
| Duitsland | de | GeoNames (CC BY 4.0) | Postcode — via /v1/de/postcode |
| Denemarken | dk | DAWA | Op de roadmap |
Een lookup kost in elk land 1 call van je maandtegoed. Niet-ondersteunde landcodes geven een nette 404 met het veld supported.
Sandbox
Gebruik je sandbox API key voor ontwikkeling en testen. De sandbox retourneert altijd vaste testresponses — er worden geen echte BAG-lookups gedaan en calls tellen niet mee voor je maandbudget.
| Postcode | Huisnummer | Adres | Stad |
|---|---|---|---|
| 1021JT | 19 | Hamerstraat | Amsterdam |
| 2585EM | 79 | Lange Voorhout | Den Haag |
| 3011AD | 1 | Coolsingel | Rotterdam |
| 5611AZ | 1 | Nachtegaallaan | Eindhoven |
| 9726AB | 1 | Paterswoldseweg | Groningen |
| 6545CA | 299 | → retourneert 404 | |
Codevoorbeelden
Voorbeelden voor de meestgebruikte talen en platformen.
curl -s \ -H "X-Api-Key: JOUW-API-KEY" \ "https://api.postcode-service.nl/v1/address/1021JT/19"
<?php
$postcode = '1021JT';
$huisnummer = '19';
$apiKey = 'JOUW-API-KEY';
$ch = curl_init("https://api.postcode-service.nl/v1/address/{$postcode}/{$huisnummer}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: {$apiKey}"]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status === 200) {
$address = json_decode($response, true);
echo $address['address'] . ', ' . $address['city'];
} else {
echo "Fout: HTTP {$status}";
}
const response = await fetch(
'https://api.postcode-service.nl/v1/address/1021JT/19',
{ headers: { 'X-Api-Key': 'JOUW-API-KEY' } }
);
const data = await response.json();
console.log(`${data.address}, ${data.city}`);
import requests
response = requests.get(
'https://api.postcode-service.nl/v1/address/1021JT/19',
headers={'X-Api-Key': 'JOUW-API-KEY'}
)
data = response.json()
print(f"{data['address']}, {data['city']}")
package main
import (
"encoding/json"
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET",
"https://api.postcode-service.nl/v1/address/1021JT/19", nil)
req.Header.Set("X-Api-Key", "JOUW-API-KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var data map[string]any
json.NewDecoder(resp.Body).Decode(&data)
fmt.Printf("%s, %s\n", data["address"], data["city"])
}
import java.net.URI;
import java.net.http.*;
import com.fasterxml.jackson.databind.ObjectMapper;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.postcode-service.nl/v1/address/1021JT/19"))
.header("X-Api-Key", "JOUW-API-KEY")
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
var data = new ObjectMapper().readValue(response.body(), Map.class);
System.out.println(data.get("address") + ", " + data.get("city"));
using System.Net.Http;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "JOUW-API-KEY");
var json = await client.GetStringAsync(
"https://api.postcode-service.nl/v1/address/1021JT/19");
var data = JsonDocument.Parse(json).RootElement;
Console.WriteLine($"{data.GetProperty("address").GetString()}, " +
$"{data.GetProperty("city").GetString()}");
require 'net/http'
require 'json'
uri = URI('https://api.postcode-service.nl/v1/address/1021JT/19')
req = Net::HTTP::Get.new(uri)
req['X-Api-Key'] = 'JOUW-API-KEY'
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
data = JSON.parse(response.body)
puts "#{data['address']}, #{data['city']}"