Postcode API (3.0.0)

Download OpenAPI specification:Download

This is the API reference of Postcode API (version 3). The API currently only supports the lookup function in order to retreive the street and city belonging to a given postcode and number. If you are looking for more information about this API, SDK's or plugins (e.g. for Wordpress), be sure to check out our documentation page (Dutch only) at https://www.postcodeapi.nu/docs.

Run in Postman

Production API

The base URI of the production API is https://api.postcodeapi.nu/v3. Requests to this API can only be made with a valid API key belonging to a paid subscription. Every request made to this API will be deducted from your subscription limits. For testing and development purposes we strongly advise to use the Sandbox API instead.

Sandbox API

The base URI of the sandbox API https://sandbox.postcodeapi.nu/v3. Requests to this API can be made with a valid API key belonging to a paid subscription or with a free sandbox API key. Requests made to this API do not affect your subscription limits. The sandbox API is identical to the production API, but it only returns a couple of addresses. Therefore, it makes no sense to use the sandbox API in your production environment. Valid postcode/number combinations are listed in the table below.

PostcodeNumberTestcase
6545CA29200 OK, address found: Waldeck Pyrmontsingel, Nijmegen, Gelderland
1021JT19200 OK, address found: Hamerstraat, Amsterdam, Noord-Holland
5038EA17200 OK, address found: Stationsstraat, Tilburg, Noord-Brabant
3030AC100200 OK, address found: Postbus, Leusden, Utrecht
6545CA29a400 Bad request, invalid number format
6545C29400 Bad request, invalid postcode format
6545C29a400 Bad request, invalid postcode and number format
6545CA299404 Not found, address not found

Authentication

ApiKey

Both APIs only work with a valid API key. In your request, the value of the key must be provided in the X-Api-Key request header.

Security Scheme TypeAPI Key
Header parameter name:X-Api-Key

Lookup

The lookup function returns the street, city, municipality, province and location belonging to the given postcode and number.

Authorizations:
path Parameters
postcode
required
string^[0-9]{4}[a-zA-Z]{2}$
Example: 6545CA

Postcode in P6 format: 4 numbers followed by 2 letters without whitespaces (e.g. 1234AB).

number
required
integer
Example: 29

Number of the address. Must be an integer. Additions (like 29-A) are not allowed as they do not affect the result of this lookup function.

Responses

Response samples

Content type
application/json
{
  • "postcode": "6545CA",
  • "number": 29,
  • "street": "Binderskampweg",
  • "city": "Nijmegen",
  • "municipality": "Nijmegen",
  • "province": "Gelderland",
  • "location": {
    }
}