logo
API docs by Redocly

UPU Postal address validation services (1.0.0)

Download OpenAPI specification:

E-mail: postcode@upu.int

Services to assist in address autocomplete, finding postcode for address.

get_adr_hint

For a 2 or 3 character iso 3166-1 code of country and a string returns collection of address hints that best match provided string. It also returns adr_id and code of script in which hints are written that can be used to retrieve full address using get_adr function.

Authorizations:
apiKey
query Parameters
country
required
string [ 2 .. 3 ] characters ^[A-Z]{2,3}$
Example: country=CHE, CH

Country alpha-2 or alpha-3 code

query
required
string [ 1 .. 255 ] characters ^.{1,255}$
Example: query=Weltpos

Beginning of the street/address.

header Parameters
ukey
required
string [ 64 .. 256 ] characters ^[A-Za-z0-9+/=-]{64,256}$

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

get_adr

Returns address for given country code, adr_id and code of script.

Authorizations:
apiKey
query Parameters
country
required
string [ 2 .. 3 ] characters ^[A-Z]{2,3}$
Example: country=CHE, CH

iso 3166-1 alpha-2 or alpha-3 code

adr_id
required
string <= 64 characters ^[A-Za-z0-9_]{64}$

Identifier of the address selected from the output of get_adr_hint.

script
required
string^[A-Z][a-z]{3}$

Code of script.

header Parameters
ukey
required
string [ 64 .. 256 ] characters ^[A-Za-z0-9+/=-]{64,256}$

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

get_pcode

Completes missing postcode for an address in ITMATT format.

Authorizations:
apiKey
query Parameters
country
required
string [ 2 .. 3 ] characters ^[A-Z]{2,3}$
Example: country=FRA, FR

iso 3166-1 alpha-2 or alpha-3 code

loc
required
string <= 120 characters ^.{,120}$
Example: loc=Nancy

Name of locality.

query
required
string [ 1 .. 320 ] characters ^.{1,320}$
Example: query=10 rue Michelet

Concatenated ITMATT premises elements.

header Parameters
ukey
required
string [ 64 .. 256 ] characters ^[A-Za-z0-9+/=-]{64,256}$

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "country": "string",
  • "pcode": "string",
  • "loc": "string",
  • "str": "string",
  • "loc_fuzzy_ratio": 100,
  • "str_fuzzy_ratio": 100,
  • "is_loc_valid": -1
}