API

JSON-REST Documentation

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

Example implementation

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

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.

Available Address API methods

rest/addresses
Dutch address lookup by postcode
rest/addresses/exact
Dutch address lookup by city, street and housenumber
rest/addresses/rd
Dutch address lookup by Rijksdriehoeksmeting coordinates
rest/addresses/latlon
Dutch address lookup by latitude and longitude

Frequently Asked Questions

Should I use GET or POST?

The Address REST API requires GET requests.

Why do I receive a 404 error if the address is not found?

We use HTTP Status codes to classify success or error reasons. For instance, if an address is successfully found, the reponse has the '200 OK' status. However if the address does not exist, we return a '404 NOT FOUND' instead. Please test edge cases like non existent addresses, missing or invalid credentials, invalid parameters, etc.

Why do I receive a 409 error for an address?

A small subset of addresses (around 300) have the same city, street and house number in the Netherlands, because the official city name itself is not unique within the Netherlands. The Address.matchExact method will return a '409 Conflict' status in the case such an address is requested. This name conflict can be resolved by adding a municipality or province suffix to the city name.

Browser clients and jsonp support

We do not support jsonp. We recommend to host a simple proxy script on your own server instead of making cross domain calls directly in the browser. This way, you also do not have to put your key and secret in publicly readable javascript.

I am getting a warning about SSLv3 when connecting

Our services are only available using safe HTTPS implementations. We do not support the older SSL(v3) protocol when communicating over HTTPS, instead use the more secure TLS protocol (v1.0-v1.2). Most internet communication libraries will support TLS automatically.