Summary
The ACI API provides a method to validate a postal address in almost all countries of the world. A successful query will return a list of matching addresses.
HTTP Request
| Method
| Endpoint
|
| GET | https://api.postnl.nl/v4/address/international |
The endpoint above requires an apikey HTTP header containing the API key provided by PostNL.
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 |
| cityName | Recommended | String | Antwerpen |
| postalCode | Recommended | String | 2000 |
| streetName | Recommended | String | Oude Koornmarkt |
| houseNumber | Recommended | String | 39 |
| houseNumberAddition | Optional | String | A |
| addressLine | Optional | String | Oude Koornmarkt 39 |
| buildingName | Optional | String | De Molensteen |
| flat | Optional | String | Flat 2 |
| stairs | Optional | String | 3 |
| floor | Optional | String | 2 |
| door | Optional | String | C |
| bus | Optional | String | 1 |
E.g.
https://api.postnl.nl/v4/address/international?countryIso=BE&cityName=Antwerpen&streetName=Grotesteenweg&houseNumber=521&bus=1
https://api.postnl.nl/v4/address/international?countryIso=BEL&postalCode=2600&cityName=Antwerpen&addressLine=Grotesteenweg 3 bus 1
addressLine input field
The addressLine field is a generic search method that can be used for all countries worldwide. Using the addressLine you can fill in the information of multiple other fields combined, such as street, house number, house number addition, postal code and city. Our code will recognize the different parts of the address. Recognizing the right parts of the address is complex, so we recommend to use the dedicated fields if possible. Having the different parts of the address in a commonly used order will increase the recognizing. i.e. addressLine=Oude Koornmarkt 39 Antwerpen NOTE: For Dutch addresses the addressLine field is not supported.
Country specific information
This API supports over 250 countries, regions, island groups. You can download the list here. Input field per country Each country has their own specific ways to describe an address. For 13 country’s we include a summary in the table below. For all other country’s we follow the UPU standard.
Input field per country
Each country has their own specific ways to describe an address. For 13 country’s we include a summary in the table below. For all other country’s we follow the UPU standard.
| Fieldname | AUT | BEL | CHE | DEU | DNK | ESP | FRA | GBR | ITA | LUX | NLD | SWE | USA |
| countryIso | M | M | M | M | M | M | M | M | M | M | M | M | M |
| cityName | R | R | R | R | R | R | R | R | R | R | R | R | R |
| postalCode | R | R | R | R | R | R | R | R | R | R | R | R | R |
| streetName | R | R | R | R | R | R | R | R | R | R | R | R | R |
| houseNumber | R | R | R | R | R | R | R | R | R | R | R | R | R |
| houseNumberAddition | O | O | O | O | O | O | O | O | O | O | O | O | O |
| addressLine | O | O | O | O | O | O | O | O | O | O | O | O | O |
| buildingName | O | O | O | O | O | O | O | O | O | O | - | O | O |
| flat | - | - | - | - | - | - | O | R | - | - | - | - | - |
| stairs | O | - | - | - | O | - | - | - | - | - | - | - | - |
| floor | - | - | - | - | O | O | - | - | O | - | - | - | - |
| door | O | - | - | - | O | O | - | - | O | - | - | - | - |
| bus | - | O | - | - | - | - | - | - | - | - | - | - | - |
R = Recommended
O = Optional
- = Not Applicable
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 | Incremental identification number of the results | Number [0-5] |
| mailabilityScore | Indication of certainty that the address is mailable (see below) | 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 |
| streetName | Street name of the address | String |
| houseNumber | House number of the address | Number |
| houseNumberAddition | House number addition of the address | String |
| postalCode | Postal code of the address | String |
| cityName | City of the address | String |
| countryName | Country of the address | String |
| 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] |
| localityName | Locality of the address | String |
| stateName | State of the address | String |
| latitude | Latitudinal coordinate of address | Number [0-15] |
| longitude | Longitudinal coordinate of address | Number [0-15] |
| companyName | Name of company, when located on the address | String |
| buildingName | Name of the building | String |
| flat | Flat number of the address | String |
| stairs | Stair that the address is connected to | String |
| floor | Floor that the address is located on | String |
| door | Door of the address | String |
| bus | Bus field; used for Belgium addresses | String |
resultNumber
The index of the address in the list with matched addresses, starting with 1. The addresses are sorted bases on the result score.
mailabilityScore
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 | Definition |
| 100 | Exact unique match |
| 80 | Almost exact match. In most cases just 1 element missing, such as a postcode or street name, but match is still unique. |
| 60 | Lot of discrepancies, but unique match with our database. 5-10 |
| 40 | House number missing and less than 10 - 20 possible results. |
| 20 | House number missing more than 20 possible results. |
| 0 | No results. |
resultPercentage
The result percentage tells how much the output has changed from the input. The score varies from 0 to 100. A score of 100 indicates a perfect match and a score of 0 indicates a complete mismatch.
An example: Let’s take the existing valid address 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.
1) Input: postal code=1014AK, house number = 102
Result Score: 100
Al the fields included in the input are exactly the same as their fields in the output, so a perfect score.
2) Input: street name=Tranfomatorweg, house number=102, city name=Amstdam
Result Score: 93
Some typos in the street name and the city name.
Possible HTTP status codes
| HTTP status code | Explanation of the response |
| 200 | JSON response with requested data. If no address if found, an empty list is returned. |
| 400 | Error on customer-side. E.g. when not enough parameters are given. |
| 401 | Authorization error. |
| 403 | The request contains an address with a country not supported by this entry point. |
| 500 | Error on PostNL side. |