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
GEThttps://api.postnl.nl/v4/address/netherland

The endpoint above requires an apikey HTTP header containing the API key provided by PostNL.

Input parameters

FieldnameMandatory/optionalFormatExample
postalCodeOptionalString1234AB
cityNameOptionalStringAmsterdam
streetNameOptionalStringDam
houseNumberMandatoryString123 (only numerical values allowed)
houseNumberAdditionOptionalStringA

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.

FieldnameDescription of attributeFormat (length)Example
resultNumberIncremental identification number of the results Number [0-5] 1
mailabilityScoreIndication of certainty that the address is mailable (see below) Number [0-3] 100
resultPercentageLevel of similarity between the input and output address data Number [0-3] 95
formattedAddressThe full address according to local/national formatting standards Array of three strings [“Dam 3”, “1234AB Amsterdam”, “Netherlands”] 
streetNameStreet name of the address StringDam
houseNumberHouse number of the address Number3
houseNumberAdditionHouse number addition of the address StringA
postalCodePostal code of the address String1234AB
cityNameCity of the address StringAmsterdam
countryNameCountry of the address, Netherlands StringNetherlands
countryIso2ISO 3166-1 alpha-2 code of the country of the address, NL String [2] NL
countryIso3ISO 3166-1 alpha-3 code of the country of the address, NLD String [3] NLD
localityNameLocality of the address StringAmsterdam
stateNameState of the address StringNoord-Holland
latitudeLatitudinal coordinate of address Number [0-15] 52.07005055399152 
longitudeLongitudinal 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.

ScoreDefinition
100Exact unique match 
80Almost exact match. In most cases just 1 element missing, such as a postcode or street name, but match is still unique. 
60Lot of discrepancies, but unique match with our database. 5-10 
40House number missing and less than 10 - 20 possible results. 
20House number missing more than 20 possible results. 
0No 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.

Example request & response

Request

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 

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 codeExplanation of the response
200    JSON response with requested data. If no address if found, an empty list is returned. 
400Error on customer-side. E.g. when not enough parameters are given. 
401Authorization error. 
403The request contains an address with a country not supported by this entry point. 
500Error on PostNL side.