Documentation
Adrescheck Nederland V4
Summary
The ACN API provides a method to validate a Dutch postal address. A successful query will return a list of matching addresses.
HTTP Request
| Method
| Endpoint
|
| GET | https://api.postnl.nl/v4/address/netherlands |
The endpoint above requires an apikey HTTP header containing the API key provided by PostNL.
Input parameters
| Fieldname | Mandatory/optional | Format | Example |
|---|---|---|---|
| postalCode | Optional | String | 1234AB |
| cityName | Optional | String | Amsterdam |
| streetName | Optional | String | Dam |
| houseNumber | Mandatory | String | 123 (only numerical values allowed) |
| houseNumberAddition | Optional | String | A |
As a minimum, a valid request requires either a postal code and a house number, or a street name, city name and a house number. If all those input parameters are present, the first method is chosen.
E.g.
https://api.postnl.nl/v4/address/netherlands?postalCode=2521VA&houseNumber=3
https://api.postnl.nl/v4/address/netherlands?cityName=Den Haag&streetName=Waldorpstraat&houseNumber=3
House Number Addition
If an existing house number addition is included in the query, only this address is returned. If no house number addition or a non-existing house number addition is included, the API returns a list with all the addresses with the same house number, so all the different house number additions.
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.
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.
| Fieldname | Description of attribute | Format (length) | Example |
| resultNumber | Incremental identification number of the results | Number [0-5] | 1 |
| mailabilityScore | Indication of certainty that the address is mailable (see below) | Number [0-3] | 100 |
| resultPercentage | Level of similarity between the input and output address data | Number [0-3] | 95 |
| formattedAddress | The full address according to local/national formatting standards | Array of three strings | [“Dam 3”, “1234AB Amsterdam”, “Netherlands”] |
| streetName | Street name of the address | String | Dam |
| houseNumber | House number of the address | Number | 3 |
| houseNumberAddition | House number addition of the address | String | A |
| postalCode | Postal code of the address | String | 1234AB |
| cityName | City of the address | String | Amsterdam |
| countryName | Country of the address, Netherlands | String | Netherlands |
| countryIso2 | ISO 3166-1 alpha-2 code of the country of the address, NL | String [2] | NL |
| countryIso3 | ISO 3166-1 alpha-3 code of the country of the address, NLD | String [3] | NLD |
| localityName | Locality of the address | String | Amsterdam |
| stateName | State of the address | String | Noord-Holland |
| latitude | Latitudinal coordinate of address | Number [0-15] | 52.07005055399152 |
| longitude | Longitudinal coordinate of address | Number [0-15] | 4.325007122144882 |
NOTE: future improvements of the API can add output fields to give more information about addresses.
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 the input address is matched with the output address from our database and 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 = 102Result 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.
Example request & response
Request |
https://api.postnl.nl/v4/address/netherlandspostalCode=2521VA&houseNumber=3 |
https://api.postnl.nl/v4/address/netherlands?cityName=DenHaag&streetName=Waldorpstraat&houseNumber=3 |
Response |
[ { "cityName": "'S-GRAVENHAGE", "formattedAddress": [ "Waldorpstraat 3", "2521CA 'S-GRAVENHAGE" ], "houseNumber": 3, "houseNumberAddition": "", "latitude": 52.07005055399152, "localityName": null, "longitude": 4.325007122144882, "mailabilityScore": 100, "postalCode": "2521CA", "resultNumber": 1, "resultPercentage": 100, "stateName": "Zuid-Holland", "streetName": "Waldorpstraat" } ] |
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. |