De Postcode API gebruikt Open Data van Kadaster's BAG en Open Data van het CBS. Alle mogelijke API calls zijn beschreven in deze specificatie. Voor support en suggesties voor verbeteringen of feature requests verwijzen we je naar de issues sectie onze Open Source Github repository: https://github.com/postcodeapi/postcodeapi.

Parameters

Alle parameters die hier beschreven staan zijn query parameters en dienen als zodanig met de URL meegestuurd te worden, bijvoorbeeld:

https://api.postcodeapi.nu/v2/addresses/?postcode=1234AB&number=1

Hypermedia

Alle responses van deze API bevatten HAL hypermedia links om door de data te kunnen navigeren. Deze navigatie vind je in de _links objecten.

Authenticatie

De gehele API is beveiligd met een Api Key. Deze key heb je gekregen tijdens de registratieprocedure. Wij gebruiken deze vorm van authenticatie om het gebruik van deze dienst te kunnen monitoren en contact op te kunnen nemen met de afnemer mocht er (onbewust) misbruik van de dienst gemaakt worden.

Het meesturen van de Api Key gebeurt met de zogenaamde X-Api-Key request header. Als je API Key bijvoorbeeld a0B1c2D34D5c6b7a8 is, dan stuur je dit mee in de header: X-Api-Key: a0B1c2D34D5c6b7a8.

Een request kan als volgt gemaakt worden met CURL:

curl -H "X-Api-Key: a0B1c2D34D5c6b7a8" "https://api.postcodeapi.nu/v2/addresses/?postcode=1234AB"

Een ander voorbeeld met PHP:

// De headers worden altijd meegestuurd als array
$headers = array();
$headers[] = 'X-Api-Key: a0B1c2D34D5c6b7a8';

// De URL naar de API call
$url = 'https://api.postcodeapi.nu/v2/addresses/?postcode=1234AB';

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

// Indien de server geen TLS ondersteunt kun je met 
// onderstaande optie een onveilige verbinding forceren.
// Meestal is dit probleem te herkennen aan een lege response.
// curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);

// De ruwe JSON response
$response = curl_exec($curl);

// Gebruik json_decode() om de response naar een PHP array te converteren
$data = json_decode($response);

curl_close($curl);