Postcode API


This interface to the Postcode API uses the REST and JSON standards for communication.


Our APIs use the Cache-Control HTTP header to indicate how long the result of a call may be cached. We recommend implementing caching of retrieved results based on this header to improve the speed and efficiency of your application. Reducing the number of calls to our service may also keep your subscription costs down.


We have written an example reference client implementation for using our API via the JSON-REST endpoint for PHP:

require_once '/PATH/TO/library/PostcodeNl/Api/RestClient.php';
$client = new PostcodeNl_Api_RestClient('{your key}', '{your secret}');

// Look up the address for Dutch postcode 2012ES, housenumber 30,
// without housenumber addition.
	$address = $client->lookupAddress('2012ES', '30', '');
catch (PostcodeNl_Api_RestClient_AddressNotFoundException $e)
	die('There is no address on this postcode/housenumber combination: '. $e);
catch (PostcodeNl_Api_RestClient_InputInvalidException $e)
	die('We have input which can never return a valid address: '. $e);
catch (PostcodeNl_Api_RestClient_ClientException $e)
	die('We have a problem setting up our client connection: '. $e);
catch (PostcodeNl_Api_RestClient_AuthenticationException $e)
	die('The Postcode API service does not know who we are: '. $e);
catch (PostcodeNl_Api_RestClient_ServiceException $e)
	die('The Postcode API service reported an error: '. $e);

// Print the address data
echo var_export($address, true);

Forward compatibility

We will take care never to break existing fields or behavior without warning. Please note that we reserve the right to add new fields to responses in the future, so your client should ignore future unknown fields at any depth in the response.


HTTP Basic authentication is used, with the values of your applications Key and Secret used as username and password, respectively. You can obtain a Key and Secret by registering an application account.


Parameter values are added to the method URL according to the documented method URL template, and each parameter must be URL-encoded.


Parameters (URL-encoded):