International Address

This service provides methods to search and verify international addresses.

Summary
This service provides methods to search and verify international addresses.
This service has two methods that work slightly differently.
This method is suited to handle data entry where only partial address information is provided.
This method expects an address that is already more or less complete.
This method is deprecated, use internationalAddressSearchV2 instead
Search for up to twenty addresses related to the address information given.
This method is deprecated, use internationalAddressSearchV2 instead
The result of an international address search.
A international address result entry, with information on the status of each element.
A single international address result entry.
A single international address result entry.
The possible value for the language parameter within this service.
The format in which the country is returned.
Address Status is an 8 character string that defines a status value per address element.

Service methods

This service has two methods that work slightly differently.

The internationalAddressSearchV2 method expects a partial address and provides a list of suggestions from which the user can select the desired address.

The internationalAddressSearchInteractive method expects a more complete address and checks and completes it.  It may also return a list of suggestions.

internationalAddressSearchV2

This method is suited to handle data entry where only partial address information is provided.  Based on the partial information a list of up to 20 addresses is suggested, saving significant key strokes when entering address data.

Returns address suggestions related to the address information given.  Suggestions are ranked based on a matching percentage.  Per field status indications are also returned for every suggestion.  Any parameter may be left empty, apart from the country parameter.

Parameters

organizationName of the company or organisation at the address
buildingBuilding or subbuilding name
streetStreet search phrase
housenrHouse number search phrase
poboxPO box search phrase
localityDistrict or municipality search phrase
postcodePostalcode search phrase
provinceProvince search phrase
countryCountry of the address, required.  Accepts ISO3 country codes.
languageLanguage in which the results are returned, see Preferred Language.
country_formatThe format in which the country is returned, see Country Format.

Returns

outA InternationalAddressSearchV2Result entry.

internationalAddressSearchInteractive

This method expects an address that is already more or less complete.  It checks the correctness of the specified address, completing it if possible.  If suggestions can be generated they will be returned as well.

Returns address suggestions related to the address information given.  Suggestions are ranked based on a matching percentage.  Per field status indications are also returned for every suggestion.  Any parameter may be left empty, apart from the country parameter.

Parameters

organizationName of the company or organisation at the address
buildingBuilding or subbuilding name
streetStreet search phrase
housenrHouse number search phrase
poboxPO box search phrase
localityDistrict or municipality search phrase
postcodePostalcode search phrase
provinceProvince search phrase
countryCountry of the address, required.  Accepts ISO3 country codes.
languageLanguage in which the results are returned, see Preferred Language.
country_formatThe format in which the country is returned, see Country Format.

Returns

outA InternationalAddressSearchV2Result entry.

Deprecated methods

internationalAddressSearch

Notice

This method is deprecated, use internationalAddressSearchV2 instead

Search for up to twenty addresses related to the address information given.  The results include a matching percentage.  Any parameter may be left empty, apart from the country parameter.

Parameters

streetStreet search phrase
housenrHouse number search phrase
poboxPO box search phrase
localityDistrict or municipality search phrase
postcodePostalcode search phrase
provinceProvince search phrase
countryCountry of the address, required.  Accepts ISO3 abbreviations.
pagePage to retrieve, pages start counting at 1

Returns

outA Patterns::{Type}PagedResult of International entries.

internationalAddressLanguageSearch

Search for up to twenty addresses related to the address information given.  The results include a matching percentage.  Any parameter may be left empty, apart from the country parameter.

Parameters

streetStreet search phrase
housenrHouse number search phrase
poboxPO box search phrase
localityDistrict or municipality search phrase
postcodePostalcode search phrase
provinceProvince search phrase
countryCountry of the address, required.  Accepts ISO3 abbreviations.
languageLanguage in which the results are returned, see below.
pagePage to retrieve, pages start counting at 1

Domains

The language parameter can have the following values.

latin(default) Latin script version of the country’s primary language.  Romanizes non latin languages.
primaryThe country’s primary language.  Kanji for Japan.
secondaryThe country’s secondary language if available.  Kana for Japan.
englishSame as latin, but returns English spelling if available (ie Munich instead of München).

Returns

outA Patterns::{Type}PagedResult of International entries.

internationalAddressSearchFormatted

Notice

This method is deprecated, use internationalAddressSearchV2 instead

Search for up to twenty addresses related to the address information given.  The results include a matching percentage.  Any parameter may be left empty, apart from the country parameter.  Similar to internationalAddressLanguageSearch, but output elements contain some extra fields, amongst others the complete formatted address.  Depending on the country these fields may not be available.

Parameters

streetStreet search phrase
housenrHouse number search phrase
poboxPO box search phrase
localityDistrict or municipality search phrase
postcodePostalcode search phrase
provinceProvince search phrase
countryCountry of the address, required.  Accepts ISO3 abbreviations.
languageLanguage in which the results are returned, see below.
pagePage to retrieve, pages start counting at 1

Domains

The language parameter can have the following values.

latin(default) Latin script version of the country’s primary language.  Romanizes non latin languages.
primaryThe country’s primary language.  Kanji for Japan.
secondaryThe country’s secondary language if available.  Kana for Japan.
englishSame as latin, but returns English spelling if available (ie Munich instead of München).

Returns

outA Patterns::{Type}PagedResult of InternationalFormattedAddress entries.

InternationalAddressSearchV2Result

The result of an international address search.

validation_statusIndicates the status of the input address.
N1No validation performed because country not recognized
N2No validation performed because reference data for this country is not available
N5internationalAddressSearchV2 only: Insufficient information to generate suggestions
Q1internationalAddressSearchV2 only: Suggested address is not complete (enter more information)
Q2internationalAddressSearchV2 only: Suggested address is complete but combined with elements from the input (added or deleted)
Q3internationalAddressSearchV2 only: Suggestions are available
VinternationalAddressSearchInteractive only: The input address is correct.
CinternationalAddressSearchInteractive only: The input address has been corrected.
P1internationalAddressSearchInteractive only: Data cannot be corrected and unlikely to be deliverable
P2internationalAddressSearchInteractive only: Data cannot be corrected, but fair chance that the address is deliverable
P3internationalAddressSearchInteractive only: Data cannot be corrected, but is very likely to be deliverable.  The supplied address may be correct.  The P1, P2 and P3 codes indicate an increasing chance of the address being correct.  However, the function could not correct the address because the address was either incomplete or ambiguous.  Instead of correcting the address, the function determines the chance that a piece of post would arrive, given the supplied address.
resultA Patterns::{Type}Array of InternationalV2 entries.
country_iso3The ISO3 country code of the matched country.

InternationalV2

A international address result entry, with information on the status of each element.

addressAn InternationalFormattedAddress element containing address data
element_match_statusA Address Status describing how each individual address element matched the available reference data.  If two elements match this does not guarantee that they are valid in combination.  The possible values for each position are as follows.
0empty
1not found
2not checked (no reference data or no chance of success)
3matched with errors
4matched without errors
element_result_statusA Address Status describing how each address element has been modified.  Each character position corresponds to an address element, in the same way as for the ‘element_match_status’ field described above.  The possible values for each position are as follows.
0empty
1not checked
2not checked but standardized
3checked and corrected (changed or inserted)
4validated, but changed (synonyms, old names)
5validated, but standardized
6validated and unchanged
7no value returned, due to multiple possible matches

International

A single international address result entry.

matchrateA matchrate between 0 and 1, denoting how well the result matches the search parameters, one being exact and 0 being no match at all.
streetStreet name of the address
housenrHouse number of the address, if available.
poboxPO box of the address, if available.
localityLocality and/or city name of the address.  If both present, values will be separated with a linefeed character.
postcodePostalcode of the address, if available.
provinceProvince or state.
countryCountry of the address.

InternationalFormattedAddress

A single international address result entry.  Similar to International, but contains some extra fields.  Depending on the country these fields may not be available

matchrateA matchrate in percentages, denoting how well the result matches the search parameters.
streetStreet name of the address
housenrHouse number of the address, if available.
poboxPO box of the address, if available.
localityLocality and/or city name of the address.  If both present, values will be separated with a linefeed character.
postcodePostalcode of the address, if available.
provinceProvince or state.
countryCountry of the address.
countryspecific_localityCountry specific alternative notation for locality
delivery_addressLocal delivery address
formatted_addressComplete formatted address
organizationName of a company or organization, if available.
departmentName or description of the department, if available.
contactName or contact information of person, if available.
buildingName of building and / or subbuilding, if available.

Definitions

Preferred Language

The possible value for the language parameter within this service.

latinLatin script version of the country’s primary language.  Romanizes non latin languages.
database(default) Returns the output in the language that is used in the address database for a given country.
primaryThe country’s primary language.  Kanji for Japan.
secondaryThe country’s secondary language if available.  Kana for Japan.
englishSame as latin, but returns English spelling if available (ie Munich instead of München).
alternative_1First alternative language (this is the case in countries where more than one language is spoken like Belgium, Switzerland or Canada)
alternative_2Second alternative language (this is the case in countries where more than one language is spoken like Belgium, Switzerland or Canada)
alternative_3Third alternative language (this is the case in countries where more than one language is spoken like Belgium, Switzerland or Canada)

Country Format

The format in which the country is returned.

iso_2ISO2 country code
iso_3ISO3 country code
iso_numberNumeric ISO country code
abbreviationAbbreviation of the country name as seen on license plates
enName in English (default)
cnName in Chinese
daName in Danish
deName in German
enName in English
esName in Spanish
fiName in Finnish
frName in French
grName in Greek
huName in Hungarian
itName in Italian
jpName in Japanese
krName in Korean
nlName in Dutch
plName in Polish
ptName in Portuguese
ruName in Russian
saName in Arabic
seName in Swedish

Address Status

Address Status is an 8 character string that defines a status value per address element.  Each character position corresponds to an address element.

1Postal code
2Locality
3Province
4Street
5Building number
6PO Box
7Building
8Organization
This method is suited to handle data entry where only partial address information is provided.
This method expects an address that is already more or less complete.
The possible value for the language parameter within this service.
The format in which the country is returned.
The result of an international address search.
A structure that shows a page of a specific result type {Type}.
A single international address result entry.
Search for up to twenty addresses related to the address information given.
A single international address result entry.
An array of type {Type} entries.
A international address result entry, with information on the status of each element.
Address Status is an 8 character string that defines a status value per address element.