Documentatie
De postcode-service.nl API geeft je direct toegang tot alle Nederlandse adressen via de officiële BAG-data van het Kadaster. 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 |
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']}"