Skip to content

Quick Start

This is a tutorial to get started quickly with postcode-api.nl. Postcode-api.nl is an online service for looking up and retrieving addresses. With the APIs, it is possible to search for addresses in different ways:

  • DirectMatch API

Search for an address using a postcode + house number. For exact determination, some countries may also require a street name.

  • Autocomplete API

This is an API that works well for creating a drilldown menu. You've probably already seen an example of this on the homepage of: postcode-api.nl.

  • Radius API

The Radius API provides the ability to search for address(es) based on latitude and longitude. The user can then specify a radius of up to 500 meters.

Creating an Account

Of course, you first need an account, which you can create at: signup . You can additionally secure your account (2FA) and later your tokens (ACL).

Order

After registering your account, you can place an order. Choose a product from the prices page, select the plan that suits you and click/choose: "Get Started".

After ordering, you will be automatically logged into the portal (control panel): portal

Token

In the portal you can create a token (you need this to communicate with the API server). The API server of postcode-api.nl is accessible at: api.postcode-api.nl.

You can create the token via the portal on the tokens page you can choose in the top right for which service (plan) the token should be used. If you only have one plan with postcode-api.nl, you can directly click on: "Add Token".

In the dialog for the new token you can enter a name and description. These two elements are for your own administration. Finally, you can select an expiration date, with a maximum expiration date of 1 year. Choose a date that works well for you (and not for example over the weekend or your own birthday).

Data Viewer

The data viewer is an additional tool. For example, if you suspect something is missing in terms of data, or if you want to quickly check something, you can use the data viewer.

For the Netherlands, the BAG dataset is used. This also means that the official naming according to BAG is maintained. The postcode-api.nl search engine knows some known "synonyms" for searching. However, the alternative spelling is not used in the data (JSON):

  • 's-Gravenhage - Den Haag
  • 's-Hertogenbosch - Den Bosch
  • Fryslân - Friesland

Missing something or discovered something? Report it at feedback or feel free to email: info @ postcode-api.nl.

Test your token

You can easily test the created token with the well-known curl:

curl --header "Authorization: Bearer $YOUR_TOKEN" https://api.postcode-api.nl/v1/directmatch/nl/3811BN/30

Want more readable output? Use the jq program:

curl --header "Authorization: Bearer $YOUR_TOKEN" https://api.postcode-api.nl/v1/directmatch/nl/3811BN/30 | jq

The above CLI commands should result in the following output:

[
  {
    "city": "Amersfoort",
    "housenumber": "30",
    "municipality": "Amersfoort",
    "postcode": "3811BN",
    "province": "Utrecht",
    "street": "Krankeledenstraat",
    "location": {
      "rd": [
        155000.0,
        463000.0
      ],
      "wgs84": [
        52.1551744,
        5.38720621
      ]
    }
  }
]

From here you can get started with one of the APIs!