API Documentation

Introduction

The Nederland Postcode API provides access to reliable address data based on Dutch postcodes. All endpoints are GET requests and return JSON.

Base URL

https://api.nederlandpostcode.nl/

Authentication

All requests require authentication via a Bearer token in the Authorization header.

Authorization: Bearer npa_live_xxx

All tokens start with a prefix that indicates the environment:

• npa_live_ for production tokens
• npa_test_ for test tokens

With a test token you can try the API for free. Test tokens only work for the following postcodes:

• 1015CN Keizersgracht, Amsterdam (10 addresses)
• 1118BN Schiphol Boulevard, Schiphol (3 addresses)

With an account you can manage multiple projects, each with their own test and production tokens.

Endpoints

Below is an overview of the available endpoints of the Nederland Postcode API. All endpoints require authentication with a Bearer token.

Click an endpoint below for more details and example requests/responses:

• GET /v1/address
• GET /v1/coordinates
• GET /v1/energy-label
• GET /quota

GET /v1/address

This endpoint retrieves addresses based on a given postcode and house number, with an optional house number addition. This can be useful for validating addresses or obtaining additional address information. The result is always a list of addresses matching the given criteria, even if only one address is found.

Query parameters

Note: The attributes[] parameter can be used to request additional information.

Note: If the addition parameter is omitted, all addresses for the given postcode and house number are returned. If the parameter is provided but empty, addresses without an addition are searched for.

Supported extra fields

The following extra fields can be requested via the attributes[] parameter:

Example with a single address

This example retrieves the address for postcode 1012RJ and house number 147 with coordinates, district and neighborhood name. There is only one address for this combination.

GET https://api.nederlandpostcode.nl/v1/address?postcode=1012RJ&number=147&attributes[]=coordinates&attributes[]=district&attributes[]=neighborhood

{
    "data": [
        {
            "postcode": "1012RJ",
            "number": 147,
            "addition": null,
            "street": "Nieuwezijds Voorburgwal",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland",
            "details": {
                "district": {
                    "official": "Burgwallen-Nieuwe Zijde",
                    "name": "Burgwallen-Nieuwe Zijde"
                },
                "neighborhood": "Nieuwe Kerk e.o."
            },
            "coordinates": {
                "latitude": 52.37316211827917,
                "longitude": 4.890902032461384
            }
        }
    ]
}

Example with multiple addresses

This example retrieves the address for postcode 1015CN and house number 10. There are 4 addresses for this combination.

GET https://api.nederlandpostcode.nl/v1/address?postcode=1015CN&number=10

{
    "data": [
        {
            "postcode": "1015CN",
            "number": 10,
            "addition": "A",
            "street": "Keizersgracht",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1015CN",
            "number": 10,
            "addition": "B",
            "street": "Keizersgracht",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1015CN",
            "number": 10,
            "addition": "C",
            "street": "Keizersgracht",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1015CN",
            "number": 10,
            "addition": "D",
            "street": "Keizersgracht",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland"
        }
    ]
}

Example with no address

This example retrieves the address for postcode 1234AB and house number 9999. There is no address for this combination. The response contains an empty list with the 200 OK status code.

GET https://api.nederlandpostcode.nl/v1/address?postcode=1234AB&number=9999

{
    "data": []
}

GET /v1/coordinates

This endpoint retrieves addresses based on given coordinates (latitude and longitude). This can be useful for finding addresses near a specific location. Like the address endpoint, this endpoint returns an array of addresses, but sorted by distance to the given coordinates.

This endpoint always returns the coordinates of the found address. Other fields such as district are not available via this endpoint.

Query parameters

Example with a found location

This example retrieves the nearest address for the given coordinates (latitude: 52.305285, longitude: 4.750645).

GET https://api.nederlandpostcode.nl/v1/coordinates?latitude=52.305285&longitude=4.750645&limit=1

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland",
            "coordinates": {
                "latitude": 52.30528553688755,
                "longitude": 4.750645160863609
            }
        }
    ]
}

Example with no found location

If no address can be found near the given coordinates, the endpoint returns a 422 Unprocessable Content status code with an error message.

GET https://api.nederlandpostcode.nl/v1/coordinates?latitude=0&longitude=0

{
    "message": "No address found near the provided coordinates."
}

GET /v1/energy-label

This endpoint retrieves the current and historical energy labels for a given address.

Query parameters

Example with a single address

This example retrieves the energy label for postcode 1118BN and house number 800.

GET https://api.nederlandpostcode.nl/v1/energy-label?postcode=1118BN&number=800

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "energy_labels": [
                {
                    "inspection_date": "02-08-2022",
                    "valid_until_date": "02-08-2032",
                    "construction_type": "utiliteitsbouw",
                    "building_type": null,
                    "energy_label": "A+++",
                    "max_energy_demand": 98.4,
                    "max_fossil_energy_demand": 55.48,
                    "min_renewable_share": 55.3
                }
            ]
        }
    ]
}

Example with no or multiple addresses

If you retrieve an energy label for a non-existent address, or for a postcode-house number combination that yields multiple addresses, you get an error with status code 422 Unprocessable Content.

{
    "message": "No address found for the given postcode and number."
}

{
    "message": "Multiple addresses found for the given postcode and number."
}

For more information about the contents of the various fields, see the Energy label API page.

GET /quota

This endpoint retrieves the current API usage and limits for the authenticated user. This can be useful for monitoring how many requests are still available for the current period.

Note: this endpoint does not have a version number in the URL.

It can take up to 5 minutes before usage is up to date.

Quota example

This example shows the current API usage and limits for the authenticated user.

GET https://api.nederlandpostcode.nl/quota

{
    "data": {
        "quota": {
            "used": 250,
            "limit": 2000
        }
    }
}

Status codes and error handling

The API uses standard HTTP status codes to indicate the outcome of a request. Below is an overview of the most common status codes and their meaning.

Example of a validation error

This example shows a response when required fields are missing from the request. In this case the postcode and number fields are missing.

{
    "message": "The postcode field is required. (and 1 more error)",
    "errors": {
        "postcode": [
            "The postcode field is required."
        ],
        "number": [
            "The number field is required."
        ]
    }
}

Rate Limiting

To prevent abuse of the API, a rate limiting policy is in place. Each API token has a limit on the number of requests that can be made within a given time period. If this limit is exceeded, the API will return a 429 Too Many Requests status code.

There is a default limit per token to prevent server overload and to protect your token against unintended high usage. Contact our support team if you need a higher limit for your use case.

There is also a monthly quota on the total number of requests, depending on your subscription. You can view your current usage and increase your limits by logging in to your account dashboard.

Example of exceeding the per-minute limit

This example shows a response when the per-minute rate limit has been exceeded. In this case the limit is set to 60 requests per minute.

{
    "message": "Rate limit exceeded.",
    "quota": {
        "strategy": "per_minute",
        "limit": 60
    }
}

Example of exceeding the monthly limit

This example shows a response when the monthly API quota has been exceeded. In this case the limit is set to 2000 requests per month.

{
    "message": "Monthly API quota exceeded.",
    "quota": {
        "strategy": "per_month",
        "limit": 2000
    }
}

Plugins

This list contains plugins developed by us and our partners. These plugins make it easier to integrate address validation into your webshop or website.

The plugins for WordPress and other e-commerce platforms are maintained by Postcode Checkout; they also provide support and help with installing these plugins.

Have you developed a plugin yourself? Get in touch with us so we can list it here.