API

Implementation

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

Example

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

<?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,
// with no housenumber addition.
try
{
	$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.

Authentication

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.

Parameters

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

Template:

https://api.postcode.nl/rest/addresses/postcode/{postcode}/{houseNumber}/{houseNumberAddition}

Parameters (URL-encoded):

https://api.postcode.nl/rest/addresses/postcode/3024AN/212/E%20K001