API documentation
Adrescheck Internationaal v3 (Dec21)
Summary
Use this API to validate international address data, including the Netherlands, that is entered in your webshop or CRM.
Methods and endpoints
| Method | Endpoint |
| POST | https://api.postnl.nl/address/international/v3/validate |
Required headers
| Header key | Header Value | Mandatory / optional |
| apikey | Your apikey | Mandatory |
| content-type | application/json | Mandatory |
Input parameters
Fieldname | Mandatory/optional | Format | Example |
CountryIso | Mandatory | String [2] or [3], according to ISO 3166-1 ‘alpha-2’ and ‘alpha-3’, not ‘numeric-3’. | BE/BEL |
City | Recommended | String [0-50] | Antwerpen |
PostalCode | Recommended | String [0-16] | 2000 |
Street | Recommended | String [0-50] | Oude Koornmarkt |
HouseNumber | Recommended | String or Number [0-8] | 39 |
HuseNumberAddition | Optional | String [0-50] | A |
Building | Optional | String [0-50] | De molensteen |
Flat | Optional | String [0-50] | Flat 2 |
Stair | Optional | String [0-50] | 3 |
Floor | Optional | String [0-50] | 2 |
Door | Optional | String [0-50] | C |
Bus | Optional | String [0-50] | 1 |
Input field ‘strength’ per country
Address formatting is different per country. Therefore, input data fields can be more (or less) indicative of an address. We use that varying field indication ‘strength’ in our queries as well. For the most requested countries, these are the indication strengths of input fields. This overview will be updated regularly.
| CountryISO | Street | HouseNumber | HouseNumberAddition | PostalCode | City | Building | |
| Austria | Mandatory | Strong | Very strong | Normal | Very strong | Strong | Normal |
| Belgium | Mandatory | Strong | Very strong | Normal | Very strong | Strong | Normal |
| France | Mandatory | Strong | Very strong | Normal | Very strong | Strong | Normal |
| Germany | Mandatory | Strong | Very strong | Normal | Very strong | Strong | Normal |
| United Kingdom | Mandatory | Strong | Very strong | Normal | Very strong | Strong | Strong |
| Netherlands | Mandatory | Strong | Very strong | Normal | Very strong | Strong | Normal |
| Spain | Mandatory | Strong | Very strong | Normal | Very strong | Strong | Normal |
Output parameters
All fields are returned for every API call. If no data was found for a specific field, the value null will be returned.
Fieldname | Description of attribute | Format [length] |
ResultNumber | The number of results (multiple addresses in the response is temporarily unavailable) | Number [0-5] |
MailabilityScore | Indication of certainty that the address is mailable | Number [0-3] |
ResultPercentage | Level of similarity between the input and output address data | Number [0-3] |
FormattedAddress | The full address according to local/national formatting standards | Array of strings, dependent on formatting standards |
Street | Street name of the address | String [0-95] |
HouseNumber | House number of the address | Number [0-35] |
HouseNumberAddition | House number addition of the address | Number [0-35] |
PostalCode | Postal code of the address | String [0-20] |
City | City of the address | String [0-35] |
Country | Country of the address | String [0-95] |
CountryIso2 | ISO 3166-1 alpha-2 code of the country of the address | String [2] |
CountryIso3 | ISO 3166-1 alpha-3 code of the country of the address | String [3] |
CompanyName | Name of company, when located on the address | String [0-95] |
Building | Name of the building | String [0-95] |
Flat | Flat number of the address | String [0-50] |
Stair | Stair that the address is connected to | String [0-50] |
Floor | Floor that the address is located on | String [0-50] |
Door | Door of the address | String [0-50] |
Bus | Bus field; used for Belgium addresses | String [0-50] |
Locality | Locality of the address | String [0-95] |
State | State of the address | String [0-95] |
Latitude | Latitudinal coordinate of address | Number [0-15] |
Longitude | Longitudinal coordinate of address | Number [0-15] |
ResultNumber
Result Number is defined as an incremental identification number of the results. When there is one address in the output response, the result number is 1. When there is more than one address in the output response, the addresses are sorted based on the result score. The first address in the response will have a result number of 1, the second address in the output will have a result number of 2, and so on.
The mailability score (MS) is defined as how well we are able to match a given input address to an address in our address database and also based on the completeness of the input and output. Scores from 0 to 100 are given back in the output. If there are different possible matches to the input provided, then the mailability score varies due to that. What each score means, is shown in the table below.
| Score | Defintion |
| 100 | Exact unique match |
| 80 | Almost exact match. In most cases just 1 element missing, such as a postcode or streetname, but match is still unique. |
| 60 | Lot of discrepancies, but unique match with our database. 5-10 |
| 40 | Housenumber missing and less than 10 - 20 possible results. |
| 20 | Housenumber missing more than 20 possible results. |
| 0 | No results. |
The result percentage tells us how much the output has changed from the input. The score varies from 0 to 100. This is based on a multi-dimensional Levenshtein distance function. Levenshtein distance is a string metric for measuring the difference between two sequences. A score of 100 indicates a perfect match and a score of 0 indicates a complete mismatch. We do a Levenshtein on the input parameter and output of the city name, street name, and postcode.
An example: Let’s take an existing valid address such as Transformatorweg 102, 1014AK, Amsterdam. The following scenarios demonstrate how the result Scores will vary when city name, street name or postcode is different between the input and output.
- Address Input: Transformatorweg 102, 1014AK, Amsterplaats Address Output: Transformatorweg 102, 1014AK, Amsterdam Result Score: 89 Transformatorweg 102, 1014AK, Amsterplaats does not exist. The input had a wrong city name of Amsterplaats. It was a change from the correct city name of Amsterdam in the output. So the result score was reduced from a perfect 100 to 89
- Address Input: Transformatorweg 102, 1014XB, Amsterdam Address Output: Transformatorweg 102, 1014AK, Amsterdam Result Score: 87 Transformatorweg 102, 1014XB, Amsterdam does not exist. The input had a wrong postcode once again of 1014XB. Since there are two characters different from the right postcode, the result score is further reduced to 87. MX IAC Fields 2
- Address Input: Transformatorstraat 102, 1014AK, Amsterdam Address Output: Transformatorweg 102, 1014AK, Amsterdam Result Score: 91 Transformatorstraat 102, 1014AK, Amsterdam does not exist. The input had a wrong streetname of Transformatorstraat. Since the last part of the streetname are different from the right streetname, the result score is reduced to 91.
Example request & response
Request | Response |
{ "City": "Antwerpen", "PostalCode": "2600", "Street": "Grotesteenweg", "HouseNumber": "521", "Bus": "2", "CountryIso": "BE", } | [ { "ResultNumber": 1, "MailabilityScore": 100, "ResultPercentage": 100, "FormattedAddress": [ "Bus 2", "Grotesteenweg 521", "2600 Antwerpen" "Belgium" ], "Street": "Grotesteenweg", "HouseNumber": 521, "HouseNumberAddition": null, "PostalCode": "2600", "City": "Antwerpen", "Country": "Belgium", "CountryIso2": "BE", "CountryIso3": "BEL", "CompanyName": null, "Building": null, "Locality": "Berchem", "State": "Antwerpen", "Latitude": 51.1807092419929, "Longitude": 4.4316843863965, "Flat": null, "Stair": null, "Floor": null, "Door": null "Bus": "2" } ] |
Possible error codes
Error code | Error message |
200 | JSON response with requested data. |
200 | Address not found. Example: [] |
4xx | Error on customer-side. Example: { "errors": [ { "status": "400", "title": "Bad Request", "detail": "Query must include valid CountryIso" } ] } |
5xx | Error on PostNL side. |