Documentation

Adrescheck International V4

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

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
cityNameRecommendedStringAntwerpen
postalCodeRecommendedString2000
streetNameRecommendedStringOude Koornmarkt
houseNumberRecommendedString39
houseNumberAdditionOptionalStringA
addressLineOptionalStringOude Koornmarkt 39
buildingNameOptionalStringDe Molensteen
flatOptionalStringFlat 2
stairsOptionalString3
floorOptionalString2
doorOptionalStringC
busOptionalString1
NOTE: future improvements of the API can add extra optional input parameters.

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.


FieldnameAUTBELCHEDEUDNKESPFRAGBRITALUXNLDSWEUSA
countryIsoMMMMMMMMMMMMM
cityNameRRRRRRRRRRRRR
postalCodeRRRRRRRRRRRRR
streetNameRRRRRRRRRRRRR
houseNumberRRRRRRRRRRRRR
houseNumberAdditionOOOOOOOOOOOOO
addressLineOOOOOOOOOOOOO
buildingNameOOOOOOOOOO-OO
flat------OR-----
stairsO---O--------
floor----OO--O----
doorO---OO--O----
bus-O-----------
M = Mandatory
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.

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.

Example request & response

Request

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=BE&postalCode=2600&cityName=Antwerpen&addressLine=Grotesteenweg 3 bus 1

Response

[ 

  { 

    "buildingName": null, 

    "bus": "1", 

    "cityName": "Antwerpen", 

    "companyName": null, 

    "countryIso2": "BE", 

    "countryIso3": "BEL", 

    "countryName": "Belgium", 

    "door": null, 

    "flat": null, 

    "floor": null, 

    "formattedAddress": [ 

      "Bus 1", 

      "Grotesteenweg 3", 

      "2600 Antwerpen", 

      "Belgium" 

    ], 

    "houseNumber": 3, 

    "houseNumberAddition": null, 

    "latitude": 51.19872787864764, 

    "localityName": "Berchem", 

    "longitude": 4.415131884851253, 

    "mailabilityScore": 100, 

    "postalCode": "2600", 

    "resultNumber": 1, 

    "resultPercentage": 92, 

    "stairs": null, 

    "stateName": "Antwerpen", 

    "streetName": "Grotesteenweg" 

  } 

]

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.