Documentation REST

Geo Adrescheck Nationaal

Summary

Simply use the API to check address data that is entered in your webshop or CRM.

Method

The following methods are defined within the Adrescheck Internationaal.

MethodDescription
https://api.postnl.nl/address/international/v1/validateAPI that validates international addresses in a general format (send any of a list of pre-defined fields).
https://api.postnl.nl/address/international/v1/labelformatAPI that validates international addresses in a label format (send 3 strings in unspecified order).

Use of services

Calling a service
A service is called by sending a message to a service endpoint. The message contains a header with security information (API-key) and the content type. The body contains the service method and related parameters.

Below you can see examples of the header and body, within Postman (an API tool to visualize APIs). Please note: the content used is purely for illustration purposes.

Example header (paste the API in “{{apikey}}”:

Adrescheck Internationaal - API key

Example body:

Adrescheck Internationaal - Example body

Each message that is received by the API is authenticated and authorized. The authorization mechanism determines if the user has access to the requested service.

After processing the request, the service will return a message with a response. The message contains a body with the information.

Parameter specification / field order
For each API, the parameters of a service are specified. Also, the behavior of these parameters are detailed. It is important to maintain the exact order of the fields as specified in the documentation [hyperlink documentatie tab]. Changing the order of fields will result in unspecified errors returned back at the client.

Security information
Each service is secured with an API-key. You can find your API-key in the API Manager. Quotamanager is secured with a username and password. If you don’t have credentials for Quotamanager yet, please fill in the form on this link.

Call details

Preview the API call buildup below. 

Method: https://api.postnl.nl/address/international/v1/validate

Scenario 1;When given correct input, the output should in most cases be a single output with a high mailability score and a high result score nearing 100.

Please note; The input set-up does not differ per country, although the use of elements differs per country. 

Input

{
    "City": "Milano",
    "Country": "ITA",
    "PostalCode": "20138",
    "Street" : "Via Gaudenzio Fantoli",
    "HouseNumber" : "6",
    "Building" : "",
    "SubBuilding" : ""
}

Output

[
  {
    "ResultNumber": 1,
    "MailabilityScore": 100,
    "ResultPercentage": 100,
    "Country": "ITALY",
    "Province": "",
    "City": "MILANO",
    "PostalCode": 20128,
    "Street": "VIA GAUDENZIO FANTOLI",
    "HouseNumber": 6,
    "FormattedAddress": [
      "VIA GAUDENZIO FANTOLI 6",
      "20138 MILANO",
      "ITALY"
   ]
]

Scenario 2; If a perfect match can not be made, multiple suggestions are returned to help you (or the end-user) choose one. In those cases up to 20 best results will be returned, sorted based on the mailability score and result percentage.

In general, to receive optimum results, it is advised to provide as many details in the input.

Please note; Although delimiters are no mandatory, better suggestions can be made for input with element seperators (comma or semicolon).

Input

{
    "City": "Milano",
    "Country": "ITA",
    "PostalCode": "0000000",
    "Street" : "Via Gaudenzio Fantoli",
    "HouseNumber" : "6",
    "Building" : "",
    "SubBuilding" : ""
}

Output

[
  {
    "ResultNumber": 1,
    "MailabilityScore": 60,
    "ResultPercentage": 50,
    "Country": "ITALY",
    "Province": "",
    "City": "MILANO",
    "PostalCode": 20128,
    "Street": "VIA GAUDENZIO FANTOLI",
    "HouseNumber": 6,
    "FormattedAddress": [
      "VIA GAUDENZIO FANTOLI 6",
      "20138 MILANO",
      "ITALY"
    ]


  },


  {

    "ResultNumber": 2,
    "MailabilityScore": 40,
    "ResultPercentage": 30,
    "Country": "ITALY",
    "Province": "",
    "City": "MILANO",
    "PostalCode": 20128,
    "Street": "VIA GAUDENZIO FANTOLI",
    "HouseNumber": 12,
    "FormattedAddress": [
      "VIA GAUDENZIO FANTOLI 12",
      "20138 MILANO",
      "ITALY"
    ]

  }

]

Preview the API call buildup below for the label format.

Method: https://api.postnl.nl/address/international/v1/labelformat

Scenario 1;When given correct input, the output should in most cases be a single output with a high mailability score and a high result score nearing 100.

Please note; The input set-up does not differ per country, although the use of elements differs per country.

Input

{
    "Country": "ITA",
    "q1": "Via Gaudenzio Fantoli 6",
    "q2": "MILANO",
    "q3": "20138"
}

Output

[
  {
    "ResultNumber": 1,
    "MailabilityScore": 100,
    "ResultPercentage": 100,
    "Country": "ITALY",
    "Province": "",
    "City": "MILANO",
    "PostalCode": "20138",
    "Street": "VIA GAUDENZIO FANTOLI",
    "HouseNumber": "6",
    "FormattedAddress": [
      "VIA GAUDENZIO FANTOLI 6",
      "20138 MILANO",
      "ITALY"
  }
]

Scenario 2; If a perfect match can not be made, multiple suggestions are returned to help you (or the end-user) choose one. In those cases up to 20 best results will be returned, sorted based on the mailability score and result percentage.

In general, to receive optimum results, it is advised to provide as many details in the input.

Please note; Although delimiters are no mandatory, better suggestions can be made for input with element seperators (comma or semicolon).

Input

{
    "Country": "ITA",
    "q1": "Via Gaudenzio Fantoli 6",
    "q2": "MILANO",
    "q3": "000000"
}

Output

[
  {
    "ResultNumber": 1,
    "MailabilityScore": 60,
    "ResultPercentage": 50,
    "Country": "ITALY",
    "Province": "",
    "City": "MILANO",
    "PostalCode": "20138",
    "Street": "VIA GAUDENZIO FANTOLI",
    "HouseNumber": "6",
    "FormattedAddress": [
      "VIA GAUDENZIO FANTOLI 6",
      "20138 MILANO",
      "ITALY"
    ]


  },

  {

    "ResultNumber": 1,
    "MailabilityScore": 60,
    "ResultPercentage": 50,
    "Country": "ITALY",
    "Province": "",
    "City": "MILANO",
    "PostalCode": "20138",
    "Street": "VIA GAUDENZIO FANTOLI",
    "HouseNumber": "6",
    "FormattedAddress": [
      "VIA GAUDENZIO FANTOLI 6",
      "20138 MILANO",
      "ITALY"
    ]

  }

]

Requests

AttributeMandatoryFormatDescriptionExample
City String [0-35]City of the address MILANO
Country String [3]The ISO country codesITA
PostalCode String [4-10]Zipcode of the address20138
Street String [0-95]The streetname of the delivery addressVIA GAUDENZIO FANTOLI
HouseNumber String [0-35]The housenumber of the delivery address6
Building String [0-95]Name of the building 
SubBuilding String [0-95]Name of the sub building 
AttributeFormatDescriptionExample
ResultNumberString [0-50]The number of results13
MailabilityScoreString [0-3]The certainty level that the address is mailable50
ResultPercentageString [0-3]The level of matching of the output and the input100
CountryString [0-95]The country spelled out completelyITALY
StreetString [0-95]The street name of the delivery address.VIA GAUDENZIO FANTOLI
HouseNumberString [0-35]The house number of the delivery address6
PostalCodeString [4-10]Zipcode of the address20138
CityString [0-35]City of the address MILANO
Province2 Strings [0-95]Province of the City, and City (repeated) 
FormattedAddress3 Strings [0-95]Full formatted addressVIA GAUDENZIO FANTOLI 6
20138 MILANO
ITALY