logo

UPU Postal address validation services (1.0.0)

Download OpenAPI specification:Download

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.

SecurityapiKey
Request
query Parameters
country
required
string [ 2 .. 3 ] characters ^[A-Z]{2,3}$

Country alpha-2 or alpha-3 code

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

Beginning of the street/address.

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

Ok

400

Invalid country code.

401

Invalid credentials.

403

Transaction limit reached.

404

Not found.

get/get_adr_hint
Response samples
application/json; charset=utf-8
[
  • {
    }
]

get_adr

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

SecurityapiKey
Request
query Parameters
country
required
string [ 2 .. 3 ] characters ^[A-Z]{2,3}$

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

Example: country=CHE, CH
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
200

Ok

400

Invalid country code.

401

Invalid credentials.

403

Transaction limit reached.

404

Not found.

get/get_adr
Response samples
application/json; charset=utf-8
[
  • {
    }
]

get_pcode

Completes missing postcode for an address in ITMATT format.

SecurityapiKey
Request
query Parameters
country
required
string [ 2 .. 3 ] characters ^[A-Z]{2,3}$

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

Example: country=FRA, FR
loc
required
string <= 120 characters ^.{,120}$

Name of locality.

Example: loc=Nancy
query
required
string [ 1 .. 320 ] characters ^.{1,320}$

Concatenated ITMATT premises elements.

Example: query=10 rue Michelet
header Parameters
ukey
required
string [ 64 .. 256 ] characters ^[A-Za-z0-9+/=-]{64,256}$
Responses
200

Ok

400

Invalid country code.

401

Invalid credentials.

403

Transaction limit reached.

404

Not found.

get/get_pcode
Response samples
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
}