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 with your API key. Send it as a Bearer token in the Authorization header.

Authorization: Bearer npa_live_xxx

All API keys start with a prefix that indicates the environment:

• npa_live_ for live API keys
• npa_test_ for test API keys

With an account you can manage multiple projects, each with their own test and live API keys.

Test postcodes

With a test API key (npa_test_) you can try all endpoints for free. You get the same responses as with a live API key, but only for postcodes starting with 1012, 1015 or 1118, with any letter combination. Test requests do not count towards your monthly quota; a test API key does have a limit of 100 requests per day.

Want to get started right away? Use one of these addresses:

If you use a test API key with any other postcode, you get a 403 Forbidden. For the range endpoints this applies to the given reference address, for /v2/coordinates to the nearest address within the radius, and for /v1/energy-label-radius to the nearest address with an energy label within the radius.

{
    "message": "Test API-keys are limited to postcodes starting with 1012, 1015 or 1118. Use a live API-key to access all addresses."
}

Try it right away

Copy one of these requests and send your test API key in the Authorization header:

GET https://api.nederlandpostcode.nl/v1/address?postcode=1015CN&number=10
GET https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&start_number=700&end_number=900
GET https://api.nederlandpostcode.nl/v2/coordinates?latitude=52.305285&longitude=4.750645&radius=50
GET https://api.nederlandpostcode.nl/v2/energy-label?postcode=1012PS&number=20
GET https://api.nederlandpostcode.nl/v1/energy-label-range?postcode=1118BN&number=800&start_number=700&end_number=900
GET https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150

Endpoints

Below is an overview of the available endpoints of the Nederland Postcode API. All endpoints require authentication with your API key. Click an endpoint for more details and example requests and responses.

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/address-range

The address range endpoint allows you to retrieve all addresses on the same street as a given address. The provided postcode and house number are used to determine the street.

This is useful, for example, when you want to retrieve all residential units of a homeowners' association (VvE), apartment complex, or a particular street. Because a street can contain multiple postcode areas, the returned addresses may have different postcodes. You can use start_number and end_number to limit the results to a specific range of house numbers. The results are paginated using page and per_page. Use attributes[]=coordinates to also receive the coordinates of each address.

Query parameters

Example

The request below uses the provided postcode and house number as the reference address and retrieves the first page with up to 5 addresses on the same street.

GET https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&per_page=5&page=1

{
    "data": [
        {
            "postcode": "1118BG",
            "number": 101,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1118BG",
            "number": 103,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1118BG",
            "number": 105,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1118BG",
            "number": 107,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1118BG",
            "number": 109,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        }
    ],
    "links": {
        "first": "https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&page=1&per_page=5",
        "last": "https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&page=41&per_page=5"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 41,
        "path": "https://api.nederlandpostcode.nl/v1/address-range",
        "per_page": 5,
        "to": 5,
        "total": 203
    }
}

Practical example

Suppose you want to automatically create the residential units of a homeowners' association (VvE). The administrator enters an address they know, for example postcode 1118BN and house number 800. The API uses this address to determine the corresponding street. You can then use start_number and end_number to request, for example, house numbers 700 through 900. The API then returns all addresses within this range, including their corresponding postcodes. This is particularly useful because a street often contains multiple postcode areas: a range of, for example, 10 to 20 house numbers may share the same postcode, after which the next range may have a different postcode.

Pagination

A street can contain many addresses. Therefore, the results are automatically divided across multiple pages. Use page to request a specific page and per_page to set the number of results per page. The maximum value for per_page is 50.

GET https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&per_page=25&page=2

Filter by house number

You can optionally specify a range of house numbers using start_number and end_number. Only addresses with a house number within this range will be returned. When start_number is provided, end_number is also required, and vice versa. Leave both parameters out to retrieve all addresses on the specified street.

GET https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&start_number=700&end_number=900

The meta section of the response contains pagination information, including the current page number, the number of results per page, the total number of pages, and the total number of addresses found. The links.first and links.last fields contain the URLs for the first and last page respectively.

GET /v2/coordinates

This endpoint retrieves all addresses within a radius around the given coordinates (latitude and longitude). This can be useful for finding addresses near a specific location, for example the location of a user or a point on a map.

The results are sorted by distance to the given point, nearest address first. Addresses at the same distance, such as apartments in the same building, are sorted by postcode, house number and addition. Each address always includes its coordinates and the distance to the given point. The attributes[] parameter is not supported by this endpoint.

Query parameters

Example

The request below retrieves all addresses within 50 meters of Schiphol Boulevard 800 (latitude: 52.305285, longitude: 4.750645).

GET https://api.nederlandpostcode.nl/v2/coordinates?latitude=52.305285&longitude=4.750645&radius=50

{
    "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
            },
            "distance": 0
        },
        {
            "postcode": "1118BN",
            "number": 810,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland",
            "coordinates": {
                "latitude": 52.30556719835437,
                "longitude": 4.750419372039126
            },
            "distance": 35
        }
    ],
    "links": {
        "first": "https://api.nederlandpostcode.nl/v2/coordinates?latitude=52.305285&longitude=4.750645&radius=50&page=1",
        "last": "https://api.nederlandpostcode.nl/v2/coordinates?latitude=52.305285&longitude=4.750645&radius=50&page=1"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.nederlandpostcode.nl/v2/coordinates",
        "per_page": 10,
        "to": 2,
        "total": 2
    }
}

The distance field is the distance in whole meters between the given point and the address.

Pagination

Use page to request a specific page and per_page to set the number of results per page (maximum 25). The meta and links sections are the same as those of the address range endpoint; meta.total counts all addresses within the radius.

No addresses found or invalid parameters

If there are no addresses within the radius, you get a 200 OK with an empty data array. If a required parameter is missing or a value is invalid, for example a radius larger than 1000 meters, you get a 422 Unprocessable Content with a validation error.

GET /v2/energy-label

This endpoint retrieves all energy labels of one specific address. Besides the validated address (street and city), you receive the full energy_labels array: not only the current label, but also any historical labels of the same building, including detailed energy performance data.

Want to retrieve the energy labels of an entire street or a range of house numbers at once? Use the /v1/energy-label-range endpoint instead. Looking for the energy labels of all addresses near a location? Use the /v1/energy-label-radius endpoint.

Query parameters

Example with a single address

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

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

{
    "data": {
        "postcode": "1118BN",
        "number": 800,
        "addition": null,
        "street": "Schiphol Boulevard",
        "city": "Schiphol",
        "energy_labels": [
            {
                "registration_date": "30-08-2022",
                "inspection_date": "02-08-2022",
                "valid_until_date": "02-08-2032",
                "status": "bestaand",
                "construction_type": "utiliteitsbouw",
                "building_type": null,
                "energy_label": "A+++",
                "calculation_type": "NTA 8800:2022 (basisopname utiliteitsbouw)",
                "inspection_type": "basis",
                "construction_year": 2019,
                "thermal_zone_area": 5648.39,
                "compactness": 1.16,
                "energy_demand": 98.4,
                "energy_demand_requirement": null,
                "primary_fossil_energy": 55.48,
                "primary_fossil_energy_requirement": null,
                "primary_fossil_energy_emg": null,
                "renewable_energy_share": 55.3,
                "renewable_energy_share_requirement": null,
                "renewable_energy_share_emg": null,
                "calculated_energy_consumption": 55.48,
                "heat_demand": 55.02,
                "calculated_co2_emission": 13.01,
                "temperature_excess": 0,
                "temperature_excess_requirement": null
            }
        ]
    }
}

Example with an address without an energy label

If the address exists but has no registered energy label, that is not an error: you get a 200 OK with the address fields filled in and an empty energy_labels array. So check for an empty array rather than for an error code.

{
    "data": {
        "postcode": "...",
        "number": ...,
        "addition": null,
        "street": "...",
        "city": "...",
        "energy_labels": []
    }
}

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. For multiple addresses, send an addition to select the right one. To select the address without an addition, send an empty addition=.

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

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

A detailed explanation of every field in the response, such as the BENG indicators and the possible label classes, can be found in the Energy label API documentation on EnergielabelAPI.nl (in Dutch).

GET /v1/energy-label-range

The energy label range endpoint lets you retrieve the energy labels of multiple addresses in a single request: of an entire street or of a specific range of house numbers on that street. This is useful, for example, for an apartment complex, a homeowners' association (VvE) or a housing block.

Just like with the address range endpoint, the provided postcode and house number are used to determine the street. Because a street can contain multiple postcode areas, the returned addresses may have different postcodes.

This endpoint differs from /v2/energy-label in a few ways:

• For each address you only receive the most recent energy label, as an energy_label object (singular), without history. If you need the full label history of an address, use /v2/energy-label.
• Only addresses with at least one registered energy label are returned. A house number without a label does not appear in the response.
• The results are paginated using page and per_page.

Query parameters

Example

The request below uses postcode 1118BN and house number 800 as the reference address and retrieves the energy labels of house numbers 700 through 900 on the same street. Only the addresses with a registered energy label are returned.

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

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 701,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "energy_label": {
                "registration_date": "30-04-2026",
                "inspection_date": "23-03-2026",
                "valid_until_date": "23-03-2036",
                "status": "bestaand",
                "construction_type": "utiliteitsbouw",
                "building_type": null,
                "energy_label": "A+",
                "calculation_type": "NTA 8800:2024 (detailopname utiliteitsbouw)",
                "inspection_type": "detail",
                "construction_year": 2015,
                "thermal_zone_area": 25941.84,
                "compactness": 0.51,
                "energy_demand": 54.33,
                "energy_demand_requirement": null,
                "primary_fossil_energy": 162.4,
                "primary_fossil_energy_requirement": null,
                "primary_fossil_energy_emg": null,
                "renewable_energy_share": 23.5,
                "renewable_energy_share_requirement": null,
                "renewable_energy_share_emg": null,
                "calculated_energy_consumption": 162.39,
                "heat_demand": 7.31,
                "calculated_co2_emission": 34.25,
                "temperature_excess": null,
                "temperature_excess_requirement": null
            }
        },
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "energy_label": {
                "registration_date": "30-08-2022",
                "inspection_date": "02-08-2022",
                "valid_until_date": "02-08-2032",
                "status": "bestaand",
                "construction_type": "utiliteitsbouw",
                "building_type": null,
                "energy_label": "A+++",
                "calculation_type": "NTA 8800:2022 (basisopname utiliteitsbouw)",
                "inspection_type": "basis",
                "construction_year": 2019,
                "thermal_zone_area": 5648.39,
                "compactness": 1.16,
                "energy_demand": 98.4,
                "energy_demand_requirement": null,
                "primary_fossil_energy": 55.48,
                "primary_fossil_energy_requirement": null,
                "primary_fossil_energy_emg": null,
                "renewable_energy_share": 55.3,
                "renewable_energy_share_requirement": null,
                "renewable_energy_share_emg": null,
                "calculated_energy_consumption": 55.48,
                "heat_demand": 55.02,
                "calculated_co2_emission": 13.01,
                "temperature_excess": 0,
                "temperature_excess_requirement": null
            }
        }
    ],
    "links": {
        "first": "https://api.nederlandpostcode.nl/v1/energy-label-range?postcode=1118BN&number=800&start_number=700&end_number=900&page=1",
        "last": "https://api.nederlandpostcode.nl/v1/energy-label-range?postcode=1118BN&number=800&start_number=700&end_number=900&page=1"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.nederlandpostcode.nl/v1/energy-label-range",
        "per_page": 10,
        "to": 2,
        "total": 2
    }
}

The energy_label object contains the same fields as the items in the energy_labels array of /v2/energy-label.

Pagination

Use page to request a specific page and per_page to set the number of results per page (maximum 25). The meta and links sections are the same as those of the address range endpoint; meta.total only counts the addresses with an energy label. Leave out start_number and end_number to retrieve the energy labels of the entire street.

No address or no energy labels found

If the reference address cannot be found, you get a 422 Unprocessable Content with the message No address found for the given postcode and number. If there are no addresses with an energy label within the given range, you get a 200 OK with an empty data array.

A detailed explanation of every field in the response, such as the BENG indicators and the possible label classes, can be found in the Energy label API documentation on EnergielabelAPI.nl (in Dutch).

GET /v1/energy-label-radius

The energy label radius endpoint lets you retrieve the energy labels of all addresses within a radius around a coordinate in a single request. This is useful, for example, to show the energy labels in a neighborhood on a map, to compare a home with its surroundings or to analyze an area.

The results are sorted by distance to the given point, nearest address first. Addresses at the same distance, such as apartments in the same building, are sorted by postcode, house number and addition. Only have an address? Retrieve its coordinates first via the address endpoint with attributes[]=coordinates.

This endpoint differs from the other energy label endpoints in a few ways:

• For each address you only receive the label class of the most recent energy label, as a string in the energy_label field (e.g. "A+"), without the other energy performance data. If you need all data or the label history of an address, use /v2/energy-label.
• Only addresses with at least one registered energy label are returned. A house number without a label does not appear in the response.
• Each address always includes its coordinates and the distance to the given point. The attributes[] parameter is not supported by this endpoint.
• The results are paginated using page and per_page.

Query parameters

Example

The request below retrieves the energy labels of all addresses within 150 meters of Schiphol Boulevard 800 (latitude: 52.305285, longitude: 4.750645). Only the addresses with a registered energy label are returned.

GET https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "coordinates": {
                "latitude": 52.30528553688755,
                "longitude": 4.750645160863609
            },
            "distance": 0,
            "energy_label": "A+++"
        },
        {
            "postcode": "1118CX",
            "number": 308,
            "addition": null,
            "street": "Evert van de Beekstraat",
            "city": "Schiphol",
            "coordinates": {
                "latitude": 52.30482565215747,
                "longitude": 4.749222421097077
            },
            "distance": 110,
            "energy_label": "A+"
        },
        {
            "postcode": "1118CL",
            "number": 1,
            "addition": null,
            "street": "Evert van de Beekstraat",
            "city": "Schiphol",
            "coordinates": {
                "latitude": 52.30549394509628,
                "longitude": 4.752529225036044
            },
            "distance": 130,
            "energy_label": "A+"
        }
    ],
    "links": {
        "first": "https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150&page=1",
        "last": "https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150&page=1"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.nederlandpostcode.nl/v1/energy-label-radius",
        "per_page": 10,
        "to": 3,
        "total": 3
    }
}

The distance field is the distance in whole meters between the given point and the address. The energy_label field contains the label class of the most recent energy label (A+++++ to G), or null if no label class is known for that label.

Pagination

Use page to request a specific page and per_page to set the number of results per page (maximum 25). The meta and links sections are the same as those of the address range endpoint; meta.total only counts the addresses with an energy label within the radius.

No energy labels found or invalid parameters

If there are no addresses with an energy label within the radius, you get a 200 OK with an empty data array. If a required parameter is missing or a value is invalid, for example a radius larger than 1000 meters, you get a 422 Unprocessable Content with a validation error.

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 key 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 API key to prevent server overload and to protect your API key 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-second limit

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

{
    "message": "Rate limit exceeded.",
    "quota": {
        "strategy": "per_second",
        "limit": 10
    }
}

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.