Postnl.nl

Documentation

Adrescheck Benelux V2

Summary

The ACB API provides a method to validate a postal address in Belgium, the Netherlands or Luxemburg (Benelux). A successful query will return a list of matching addresses.

HTTP Request


Method
Endpoint
GEThttps://api.postnl.nl/v2/address/benelux

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

Input parameters

FieldnameMandatory/optionalFormatExample
countryIsoMandatoryString [2] or [3], according to ISO 3166-1 ‘alpha-2’ and ‘alpha-3’, not ‘numeric-3’. BE
cityNameRecommended StringAntwerpen
postalCodeRecommended String2000
streetNameRecommended StringOude Koornmarkt 
houseNumberRecommended String39
houseNumberAdditionOptional StringA
addressLineOptional StringOude Koornmarkt 39 Antwerpen 
busOptional String1
NOTE: future improvements of the API can add extra optional input parameters.

E.g.

https://api.postnl.nl/v2/address/benelux?countryIso=BE&cityName=Antwerpen&streetName=Grotesteenweg&houseNumber=521&bus=1
https://api.postnl.nl/v2/address/benelux?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. Supported countries This API supports the Benelux area, Belgium, Netherlands and Luxemburg.

Supported countries

This API supports the Benelux area, Belgium, Netherlands and Luxemburg.

Input fields per country

FieldnameBELLUXNLD
countryIsoMMM
cityNameRRR
postalCodeRRR
streetNameRRR
houseNumberRRR
houseNumberAdditionOOO
addressLineOO-
busO--
M = Mandatory
R = Recommended
O = Optional
- = Not Applicable

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)
resultNumberIncremental identification number of the results Number [0-5] 
mailabilityScoreIndication of certainty that the address is mailable (see below) Number [0-3] 
resultPercentageLevel of similarity between the input and output address data Number [0-3] 
formattedAddressThe full address according to local/national formatting standards Array of strings, dependent on formatting standards 
streetNameStreet name of the address String
houseNumberHouse number of the address Number
houseNumberAdditionHouse number addition of the address String
postalCodePostal code of the address String
cityNameCity of the address String
countryNameCountry of the address String
countryIso2ISO 3166-1 alpha-2 code of the country of the address String [2] 
countryIso3ISO 3166-1 alpha-3 code of the country of the address String [3] 
localityNameLocality of the address String
stateNameState of the address String
latitudeLatitudinal coordinate of address Number [0-15] 
longitudeLongitudinal coordinate of address Number [0-15] 
companyNameName of company, when located on the address String
buildingNameName of the building String
flatFlat number of the address String
stairsStair that the address is connected to String
floorFloor that the address is located on String
doorDoor of the address String
busBus field; used for Belgium addresses String
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 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.

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.

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.