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

Header
X-Api-Key: JOUW-API-KEY
Let op bij frontend-gebruik: een API key in client-side JavaScript is zichtbaar voor bezoekers. Beperk je key tot specifieke domeinen via de domeinbeperking in je dashboard, of roep de API aan vanuit je backend.

Endpoint

Alle requests zijn GET-requests zonder request body.

Omgeving Base URL
Productiehttps://api.postcode-service.nl
Sandboxhttps://sandbox.postcode-service.nl
GET /v1/address/{postcode}/{huisnummer}/{toevoeging?}

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.

GET /v1/address/1021JT/19A
{
  "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
postcodestringPostcode in hoofdletters zonder spatie
numberintegerHuisnummer
letterstring|nullHuisletter zoals meegegeven in de URL, of null
additionstring|nullToevoeging zoals meegegeven in de URL, of null
addressstringVolledig geformatteerd adres incl. huisletter en toevoeging
streetstringStraatnaam
citystringWoonplaats
municipalitystringGemeente
provincestringProvincie
locationobjectObject 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/19nullnullHamerstraat 19
/v1/address/1021JT/19AAnullHamerstraat 19A
/v1/address/1021JT/19/1null1Hamerstraat 19-1
/v1/address/1021JT/19A/bisAbisHamerstraat 19A-bis

Foutcodes

Foutresponses hebben Content-Type: application/problem+json en een JSON body met een title veld.

Status Betekenis Wanneer
200OKAdres gevonden
400Bad RequestOngeldig postcode- of huisnummerformaat
401UnauthorizedOngeldige of ontbrekende API key
403ForbiddenDomein niet toegestaan voor deze API key
404Not FoundAdres niet gevonden in de BAG-database
429Too Many RequestsRate limit overschreden (per seconde of per maand)

Rate limits

Er zijn twee onafhankelijke limieten. Bij overschrijding ontvang je HTTP 429.

Limiet Omschrijving Reset
Per secondeAfhankelijk van je plan (5–25 calls/sec). Response bevat Retry-After: 1Na 1 seconde
Per maandHet maandbudget van je abonnement1e van de maand

Response headers

Header Omschrijving
X-RateLimit-LimitMaandlimiet van je abonnement
X-RateLimit-RemainingResterende calls deze maand
X-RateLimit-ResetUnix 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
1021JT19HamerstraatAmsterdam
2585EM79Lange VoorhoutDen Haag
3011AD1CoolsingelRotterdam
5611AZ1NachtegaallaanEindhoven
9726AB1PaterswoldsewegGroningen
6545CA299→ 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']}"