Introduction
This is the Address4 API documentation.
This documentation aims to provide all the information you need to work with our API.
Base URL
https://api.address4.com
Authenticating requests
Authenticate requests to this API's endpoints by sending an Authorization
header with the value "Bearer {YOUR_APP_KEY}"
.
All authenticated endpoints are marked with a requires authentication
badge in the documentation below.
You can view and manage your API keys in the Address4 Apps.
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources.
The access token is passed with all further requests to the API using the Authorization
header, like so:
Authorization: Bearer {token}
Suggest V4
Address (full)
requires authentication
Suggestion for full address
Example request:
curl --request GET \
--get "https://api.address4.com/v3/suggest/address?query=Via+Roveggia+5c" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"query\": \"doloribus\",
\"restrict_id\": \"voluptatum\",
\"restrict_level\": \"sapiente\"
}"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/suggest/address',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'query'=> 'Via Roveggia 5c',
],
'json' => [
'query' => 'doloribus',
'restrict_id' => 'voluptatum',
'restrict_level' => 'sapiente',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/suggest/address"
);
const params = {
"query": "Via Roveggia 5c",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"query": "doloribus",
"restrict_id": "voluptatum",
"restrict_level": "sapiente"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
{
"iso3": "ITA",
"level": "street",
"id": 38000073665,
"country": "Italia",
"region": "Veneto",
"province": "Verona",
"province_code": "VR",
"city": "Verona",
"zipcode": "37136",
"street": "Via Roveggia",
"number": "5",
"exponent": "c",
"label": "Via Roveggia 5c, 37136 Verona (VR) - Italia"
},
{
"iso3": "ITA",
"level": "street",
"id": 38000860896,
"country": "Italia",
"region": "Puglia",
"province": "Taranto",
"province_code": "TA",
"city": "Manduria",
"district1": "Torre Colimena",
"zipcode": "74024",
"street": "Via 5C",
"number": "5",
"exponent": "c",
"label": "Via 5C 5c, 74024 Manduria (TA) - Italia"
},
{
"iso3": "ECU",
"level": "street",
"id": 21800019148,
"country": "Ecuador",
"province": "Pichincha",
"city": "Cayambe",
"street": "5C",
"number": "5",
"exponent": "c",
"label": "5C 5c, Cayambe - Ecuador"
},
{
"iso3": "ECU",
"level": "street",
"id": 21800012971,
"country": "Ecuador",
"province": "Azuay",
"city": "Cuenca",
"street": "5C",
"number": "5",
"exponent": "c",
"label": "5C 5c, Cuenca - Ecuador"
},
{
"iso3": "ECU",
"level": "street",
"id": 21800019281,
"country": "Ecuador",
"province": "Pichincha",
"city": "Quito",
"street": "5C",
"number": "5",
"exponent": "c",
"label": "5C 5c, Quito - Ecuador"
},
{
"iso3": "MEX",
"level": "street",
"id": 48404240605,
"country": "México",
"state": "Yucatán",
"state_code": "YUC",
"city": "Kanasín",
"zipcode": "97370",
"street": "Calle 5C",
"number": "5",
"exponent": "c",
"label": "Calle 5C 5c, 97370 Kanasín - México"
},
{
"iso3": "MEX",
"level": "street",
"id": 48404245442,
"country": "México",
"state": "Yucatán",
"state_code": "YUC",
"city": "Mérida",
"zipcode": "97130",
"street": "Calle 5C",
"number": "5",
"exponent": "c",
"label": "Calle 5C 5c, 97130 Mérida - México"
},
{
"iso3": "MEX",
"level": "street",
"id": 48404245443,
"country": "México",
"state": "Yucatán",
"state_code": "YUC",
"city": "Mérida",
"zipcode": "97133",
"street": "Calle 5C",
"number": "5",
"exponent": "c",
"label": "Calle 5C 5c, 97133 Mérida - México"
},
{
"iso3": "MEX",
"level": "street",
"id": 48404245444,
"country": "México",
"state": "Yucatán",
"state_code": "YUC",
"city": "Mérida",
"zipcode": "97204",
"street": "Calle 5C",
"number": "5",
"exponent": "c",
"label": "Calle 5C 5c, 97204 Mérida - México"
},
{
"iso3": "MEX",
"level": "street",
"id": 48404245445,
"country": "México",
"state": "Yucatán",
"state_code": "YUC",
"city": "Mérida",
"zipcode": "97217",
"street": "Calle 5C",
"number": "5",
"exponent": "c",
"label": "Calle 5C 5c, 97217 Mérida - México"
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Example response (400, Bad Request):
{
"error": {
"code": 400,
"message": "Missing the 'query'."
}
}
Received response:
Request failed with error:
Response
Response Fields
iso3
string
Country code (ISO 3166-1 alpha-3).
level
string
Territorial level of the element.
id
integer
Element ID.
country
string
Country name.
state
string
(optional) State.
state_code
string
(optional) State code.
region
string
(optional) Region.
region_code
string
(optional) Region code.
province
string
(optional) Province.
province_code
string
(optional) Province code.
city
string
City.
district1
string
(optional) Sub-locality District level 1.
zipcode
string
(optional) Postal code.
street
string
Street name.
number
string
House number.
exponent
string
Exponent.
label
string
Complete address on single line.
It contains the main territorial levels that can be showed as a label.
Country
requires authentication
Suggestion for country
Example request:
curl --request GET \
--get "https://api.address4.com/v3/suggest/country?query=Italia" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"query\": \"omnis\"
}"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/suggest/country',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'query'=> 'Italia',
],
'json' => [
'query' => 'omnis',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/suggest/country"
);
const params = {
"query": "Italia",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"query": "omnis"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
{
"iso3": "ITA",
"level": "country",
"id": 38000000001,
"country": "Italia"
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Received response:
Request failed with error:
Response
Response Fields
level
string
Territorial level of the element.
id
integer
Element ID.
iso3
string
Country code (ISO 3166-1 alpha-3).
country
string
Country name.
State
requires authentication
Suggestion for state
Example request:
curl --request GET \
--get "https://api.address4.com/v3/suggest/state?query=California&iso3=USA" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"query\": \"sit\",
\"iso3\": \"neque\"
}"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/suggest/state',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'query'=> 'California',
'iso3'=> 'USA',
],
'json' => [
'query' => 'sit',
'iso3' => 'neque',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/suggest/state"
);
const params = {
"query": "California",
"iso3": "USA",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"query": "sit",
"iso3": "neque"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
{
"iso3": "USA",
"level": "state",
"id": 84000000010,
"country": "United States",
"state": "California",
"state_code": "CA"
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Received response:
Request failed with error:
Response
Response Fields
level
string
Territorial level of the element.
id
integer
Element ID.
iso3
string
Country code (ISO 3166-1 alpha-3).
country
string
Country name.
state
string
(optional) State.
state_code
string
(optional) State code.
zipcode
string
(optional) Postal code.
Region
requires authentication
Suggestion for region
Example request:
curl --request GET \
--get "https://api.address4.com/v3/suggest/region?query=Veneto&iso3=ITA" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"query\": \"velit\",
\"iso3\": \"soluta\"
}"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/suggest/region',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'query'=> 'Veneto',
'iso3'=> 'ITA',
],
'json' => [
'query' => 'velit',
'iso3' => 'soluta',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/suggest/region"
);
const params = {
"query": "Veneto",
"iso3": "ITA",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"query": "velit",
"iso3": "soluta"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
{
"iso3": "ITA",
"level": "region",
"id": 38000000006,
"country": "Italia",
"region": "Veneto"
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Received response:
Request failed with error:
Response
Response Fields
level
string
Territorial level of the element.
id
integer
Element ID.
iso3
string
Country code (ISO 3166-1 alpha-3).
country
string
Country name.
state
string
(optional) State.
state_code
string
(optional) State code.
region
string
Region.
region_code
string
(optional) Region code.
zipcode
string
(optional) Postal code.
Province
requires authentication
Suggestion for province
Example request:
curl --request GET \
--get "https://api.address4.com/v3/suggest/province?query=Verbano&iso3=ITA" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"query\": \"atque\",
\"iso3\": \"voluptatem\",
\"restrict_id\": 3
}"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/suggest/province',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'query'=> 'Verbano',
'iso3'=> 'ITA',
],
'json' => [
'query' => 'atque',
'iso3' => 'voluptatem',
'restrict_id' => 3,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/suggest/province"
);
const params = {
"query": "Verbano",
"iso3": "ITA",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"query": "atque",
"iso3": "voluptatem",
"restrict_id": 3
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
{
"iso3": "ITA",
"level": "province",
"id": 38000000123,
"country": "Italia",
"region": "Piemonte",
"province": "Verbano Cusio Ossola",
"province_code": "VB"
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Received response:
Request failed with error:
Response
Response Fields
level
string
Territorial level of the element.
id
integer
Element ID.
iso3
string
Country code (ISO 3166-1 alpha-3).
country
string
Country name.
state
string
(optional) State.
state_code
string
(optional) State code.
region
string
(optional) Region.
region_code
string
(optional) Region code.
province
string
Province.
province_code
string
(optional) Province code.
zipcode
string
(optional) Postal code.
City
requires authentication
Suggestion for city
Example request:
curl --request GET \
--get "https://api.address4.com/v3/suggest/city?query=Vercelli&iso3=ITA" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"query\": \"omnis\",
\"iso3\": \"fuga\",
\"restrict_id\": 7
}"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/suggest/city',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'query'=> 'Vercelli',
'iso3'=> 'ITA',
],
'json' => [
'query' => 'omnis',
'iso3' => 'fuga',
'restrict_id' => 7,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/suggest/city"
);
const params = {
"query": "Vercelli",
"iso3": "ITA",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"query": "omnis",
"iso3": "fuga",
"restrict_id": 7
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
{
"iso3": "ITA",
"level": "city",
"id": 38000001682,
"country": "Italia",
"region": "Piemonte",
"province": "Vercelli",
"province_code": "VC",
"city": "Vercelli",
"zipcode": "13100"
},
{
"iso3": "ITA",
"level": "city",
"id": 38000001606,
"country": "Italia",
"region": "Piemonte",
"province": "Vercelli",
"province_code": "VC",
"city": "Borgo Vercelli",
"zipcode": "13012"
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Received response:
Request failed with error:
Response
Response Fields
level
string
Territorial level of the element.
id
integer
Element ID.
iso3
string
Country code (ISO 3166-1 alpha-3).
country
string
Country name.
state
string
(optional) State.
state_code
string
(optional) State code.
region
string
(optional) Region.
region_code
string
(optional) Region code.
province
string
(optional) Province.
province_code
string
(optional) Province code.
city
string
City.
zipcode
string
(optional) Postal code.
District1
requires authentication
Suggestion for district level 1
Example request:
curl --request GET \
--get "https://api.address4.com/v3/suggest/district1?query=Milano&iso3=ITA" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"query\": \"doloribus\",
\"iso3\": \"quis\",
\"restrict_id\": 13
}"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/suggest/district1',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'query'=> 'Milano',
'iso3'=> 'ITA',
],
'json' => [
'query' => 'doloribus',
'iso3' => 'quis',
'restrict_id' => 13,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/suggest/district1"
);
const params = {
"query": "Milano",
"iso3": "ITA",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"query": "doloribus",
"iso3": "quis",
"restrict_id": 13
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
{
"iso3": "ITA",
"level": "district1",
"id": 38001363482,
"country": "Italia",
"region": "Umbria",
"province": "Perugia",
"province_code": "PG",
"city": "Spoleto",
"district1": "Milano",
"zipcode": "06049"
},
{
"iso3": "ITA",
"level": "district1",
"id": 38000022330,
"country": "Italia",
"region": "Lombardia",
"province": "Milano",
"province_code": "MI",
"city": "Segrate",
"district1": "Milano Due",
"zipcode": "20054"
},
{
"iso3": "ITA",
"level": "district1",
"id": 38000009426,
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Ravenna",
"province_code": "RA",
"city": "Cervia",
"district1": "Milano Marittima",
"zipcode": "48015"
},
{
"iso3": "ITA",
"level": "district1",
"id": 38000019401,
"country": "Italia",
"region": "Lombardia",
"province": "Milano",
"province_code": "MI",
"city": "Basiglio",
"district1": "Milano Tre",
"zipcode": "20079"
},
{
"iso3": "ITA",
"level": "district1",
"id": 38001129710,
"country": "Italia",
"region": "Lombardia",
"province": "Milano",
"province_code": "MI",
"city": "Assago",
"district1": "Milanofiori",
"zipcode": "20057"
},
{
"iso3": "ITA",
"level": "district1",
"id": 38001308925,
"country": "Italia",
"region": "Piemonte",
"province": "Torino",
"province_code": "TO",
"city": "Torino",
"district1": "Barriera di Milano",
"zipcode": "10100"
},
{
"iso3": "ITA",
"level": "district1",
"id": 38001131341,
"country": "Italia",
"region": "Veneto",
"province": "Verona",
"province_code": "VR",
"city": "Verona",
"district1": "Borgo Milano",
"zipcode": "37100"
},
{
"iso3": "ITA",
"level": "district1",
"id": 38001129711,
"country": "Italia",
"region": "Lombardia",
"province": "Milano",
"province_code": "MI",
"city": "Assago",
"district1": "Centro Congressi Milanofiori",
"zipcode": "20057"
},
{
"iso3": "ITA",
"level": "district1",
"id": 38000017703,
"country": "Italia",
"region": "Trentino-Alto Adige",
"province": "Trento",
"province_code": "TN",
"city": "Sporminore",
"district1": "Maso Milano",
"zipcode": "38010"
},
{
"iso3": "ITA",
"level": "district1",
"id": 38000022199,
"country": "Italia",
"region": "Lombardia",
"province": "Lodi",
"province_code": "LO",
"city": "Tavazzano con Villavesco",
"district1": "Muzza di Milano",
"zipcode": "26838"
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Received response:
Request failed with error:
Response
Response Fields
level
string
Territorial level of the element.
id
integer
Element ID.
iso3
string
Country code (ISO 3166-1 alpha-3).
country
string
Country name.
state
string
(optional) State.
state_code
string
(optional) State code.
region
string
(optional) Region.
region_code
string
(optional) Region code.
province
string
(optional) Province.
province_code
string
(optional) Province code.
city
string
City.
district1
string
Sub-locality District level 1.
zipcode
string
(optional) Postal code.
Street
requires authentication
Suggestion for street
Example request:
curl --request GET \
--get "https://api.address4.com/v3/suggest/street?query=Via+Roma&iso3=ITA&restrict_id=38000004730" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"query\": \"enim\",
\"iso3\": \"dolorem\",
\"restrict_id\": 3
}"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/suggest/street',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'query'=> 'Via Roma',
'iso3'=> 'ITA',
'restrict_id'=> '38000004730',
],
'json' => [
'query' => 'enim',
'iso3' => 'dolorem',
'restrict_id' => 3,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/suggest/street"
);
const params = {
"query": "Via Roma",
"iso3": "ITA",
"restrict_id": "38000004730",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"query": "enim",
"iso3": "dolorem",
"restrict_id": 3
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
{
"level": "street",
"id": 38000073652,
"region": "Veneto",
"province": "Verona",
"province_code": "VR",
"city": "Verona",
"street": "Via Roma",
"zipcode": "37121"
},
{
"level": "street",
"id": 38001142331,
"region": "Veneto",
"province": "Verona",
"province_code": "VR",
"city": "Verona",
"street": "Via Romagna",
"zipcode": "37134"
},
{
"level": "street",
"id": 38000073653,
"region": "Veneto",
"province": "Verona",
"province_code": "VR",
"city": "Verona",
"street": "Via Beniamino Romagnoli",
"zipcode": "37139"
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Example response (400, Bad Request):
{
"error": {
"code": 400,
"message": "Missing the 'iso3'."
}
}
Received response:
Request failed with error:
Response
Response Fields
level
string
Territorial level of the element.
id
integer
Element ID.
state
string
(optional) State.
state_code
string
(optional) State code.
region
string
(optional) Region.
region_code
string
(optional) Region code.
province
string
(optional) Province.
province_code
string
(optional) Province code.
city
string
City.
district1
string
(optional) Sub-locality District level 1.
zipcode
string
(optional) Postal code.
street
string
Street name.
Zipcode
requires authentication
Suggestion for zipcode
Example request:
curl --request GET \
--get "https://api.address4.com/v3/suggest/zipcode?query=42023&iso3=ITA" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"query\": \"rem\",
\"iso3\": \"praesentium\",
\"zip_level\": \"dolorum\"
}"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/suggest/zipcode',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'query'=> '42023',
'iso3'=> 'ITA',
],
'json' => [
'query' => 'rem',
'iso3' => 'praesentium',
'zip_level' => 'dolorum',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/suggest/zipcode"
);
const params = {
"query": "42023",
"iso3": "ITA",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"query": "rem",
"iso3": "praesentium",
"zip_level": "dolorum"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "city",
"id": 38000005186,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38000013982,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Argine",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38000013983,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Seta",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38000018193,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Villa Seta",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38000022111,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Zurco",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38000027973,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Cadelbosco di Sotto",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38000030577,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Santa Vittoria",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001352004,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Argine Vecchio",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001352005,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Basetti",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001352006,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Cantone",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001352007,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "La Madonnina",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001352008,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Ponte Forca",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001352009,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Quarti",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001352010,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Stazione Bosco Sotto",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001352011,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Villa Argine",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001470449,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Corte Cantina",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001470450,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "La Tomba",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001470451,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Florida",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001470452,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Molino del Traghettino",
"zipcode": "42023"
},
{
"country": "Italia",
"region": "Emilia-Romagna",
"province": "Reggio Emilia",
"level": "district1",
"id": 38001470453,
"city": "Cadelbosco di Sopra",
"city_id": 38000005186,
"district1": "Traghettino",
"zipcode": "42023"
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Received response:
Request failed with error:
Response
Response Fields
level
string
Territorial level of the element.
id
integer
Element ID.
country
string
Country name.
state
string
(optional) State.
state_code
string
(optional) State code.
region
string
(optional) Region.
region_code
string
(optional) Region code.
province
string
(optional) Province.
province_code
string
(optional) Province code.
city
string
City.
city_id
integer
(optional) City ID of the element.
district1
string
(optional) Sub-locality District level 1.
street
string
(optional) Street name.
number
string
(optional) House number.
exponent
string
(optional) Exponent.
zipcode
string
Postal code.
building
string
(optional) Building name (only for GBR and IRL).
subbilding
string
(optional) Sub-Building information (only for GBR and IRL).
organization
string
(optional) Organization name (only for GBR and IRL).
Validation V3 - OLD
Validation API V3
requires authentication
This API will be deprecated starting 1 June 2024. Check the new Validation V4!
Example request:
curl --request GET \
--get "https://api.address4.com/v3/validation?country_code=ITA&city=verona&addr1=via+antonio+pacinotti+204" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.address4.com/v3/validation',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'country_code'=> 'ITA',
'city'=> 'verona',
'addr1'=> 'via antonio pacinotti 204',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v3/validation"
);
const params = {
"country_code": "ITA",
"city": "verona",
"addr1": "via antonio pacinotti 204",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
[
{
"result": {
"result_fl": "1"
},
"output_singleLine": "Via Antonio Pacinotti,204, Verona, VR, Veneto, 37135, Italia",
"output_smart": {
"country": "Italia",
"adm_level_main": "Verona",
"city": "Verona",
"addr": "Via Antonio Pacinotti,204",
"zipcode": "37135"
},
"output_complete": {
"country": "Italia",
"state": "",
"region": "Veneto",
"province": "Verona",
"city": "Verona",
"sub_locality_main": "",
"sub_locality1": "",
"sub_locality2": "",
"sub_locality3": "",
"postal_town": "VERONA",
"zipcode": "37135",
"addr1": "Via Antonio Pacinotti,204",
"addr2": "",
"street_name": "Via Antonio Pacinotti",
"house_number": "204",
"house_number_ext": "",
"building": "",
"subbuilding": "",
"organization": "",
"org_department": "",
"near_by": "",
"care_of": "",
"po_box": "",
"out_lng": "380"
},
"egon_codes": {
"egon_city_code": {
"lValue": 38000004730
},
"egon_sbl_code": {
"lValue": 0
},
"egon_str_code": {
"lValue": 38000073526
},
"egon_key_code": {
"lValue": 0
}
},
"adm_codes": {
"nr9Ele": {
"lValue": 12
},
"areaCode": [
{
"code_type": "50137",
"code_value": "VR"
},
{
"code_type": "30000",
"code_value": "L781"
},
{
"code_type": "30021",
"code_value": "023091"
},
{
"code_type": "30022",
"code_value": "005"
},
{
"code_type": "30030",
"code_value": "11700"
},
{
"code_type": "30050",
"code_value": "0777000"
},
{
"code_type": "30060",
"code_value": "086"
},
{
"code_type": "30061",
"code_value": "660999"
},
{
"code_type": "30070",
"code_value": "ITA"
},
{
"code_type": "30071",
"code_value": "IT"
},
{
"code_type": "30072",
"code_value": "380"
},
{
"code_type": "30114",
"code_value": "ITALIA"
}
]
},
"geocoding": {
"geo_level": "A41-261",
"long_lat": "45.40785120 , 10.96922180"
}
},
{
"WP9STC": {
"lValue": 0
}
}
]
Example response (401, Unauthorized):
{
"error": {
"code": 401,
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer {token}'). See https://account.address4.com/docs for details."
}
}
Received response:
Request failed with error:
Response
Response Fields
result.result_fl
string
Address Validation result.
- 0 = Address validated - All levels
- 1 = Address validated - Street level
- 2 = Address validated - City/Locality level
- 3 = Address not validated
output_singleLine
string
Complete address on single line. It contains all territorial levels including the country name.
output_smart.country
string
Country name.
output_smart.administrative_level
string
Main administrative level above the City.
output_smart.city
string
City.
output_smart.addr
string
Address.
output_smart.zipcode
string
Postal code.
output_complete.country
string
Country.
output_complete.state
string
State. Not every Country exhibits this territorial level.
output_complete.region
string
Region. Not every Country exhibits this territorial level.
output_complete.province
string
Province. Not every Country exhibits this territorial level.
output_complete.city
string
City.
output_complete.sub_locality_main
string
Sub-locality District main level. It contains the main sub-locality among the 3 sub_locality levels.
output_complete.locality
string
Sub-locality District level 1. Not every Country exhibits this territorial level.
output_complete.locality2
string
Sub-locality District level 2. Not every Country exhibits this territorial level.
output_complete.locality3
string
Sub-locality District level 3. Not every Country exhibits this territorial level.
output_complete.postal_town
string
Postal Town. Not every Country exhibits postal towns.
output_complete.zipcode
string
Postal code.
output_complete.addr1
string
Complete address. It contains the house number and any additional address information.
output_complete.addr2
string
Secondary address. Only for UK
output_complete.street_name
string
Street name.
output_complete.hn
string
House number + Exponent.
output_complete.hn_ext
string
House number extra information.
output_complete.building
string
Building name. Only for UK.
output_complete.subbuilding
string
Sub-Building name. Only for UK.
output_complete.organization
string
Organization Name. Only for UK.
output_complete.org_department
string
Organization Department. Only for UK.
output_complete.near_by
string
Near by.
output_complete.care_of
string
Care of.
output_complete.po_box
string
PO Box.
output_complete.out_lng
string
Output language. It indicates the language code (ISO 3166-1 numeric for native language) or the transliteration code.
egon_codes.egon_key_code
integer
Egon key code.
egon_codes.egon_str_code
integer
Egon street code.
egon_codes.egon_city_code
integer
Egon city code.
egon_codes.egon_sbl_code
integer
Egon subocality code.
adm_codes.code_type
string
Code type. It may contain statistical/administrative types of code.
adm_codes.code_value
string
Code value. Statistical/administrative code value.
geocoding.geo_level
string
Geocoding quality indicator.
geocoding.long_lat
string
Longitude and latitude. Expressed in degrees on WGS84 coordinates system format: +YY.YYYYYYY , +XX.XXXXXXX
Validation V4
Validation API V4 Address
requires authentication
Example request:
curl --request POST \
"https://api.address4.com/v4/validation/address" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"par\": {
\"iso3\": \"ITA\",
\"geo\": \"S\"
},
\"data\": {
\"address\": {
\"city\": \"Verona\",
\"street\": \"Via Pacinotti 4b\"
}
}
}"
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.address4.com/v4/validation/address',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'par' => [
'iso3' => 'ITA',
'geo' => 'S',
],
'data' => [
'address' => [
'city' => 'Verona',
'street' => 'Via Pacinotti 4b',
],
],
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v4/validation/address"
);
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"par": {
"iso3": "ITA",
"geo": "S"
},
"data": {
"address": {
"city": "Verona",
"street": "Via Pacinotti 4b"
}
}
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
{
"data": {
"address": {
"standard": {
"iso3": "ITA",
"country": "Italia",
"region": "Veneto",
"province": "Verona",
"province_code": "VR",
"city": "Verona",
"zipcode": "37135",
"street_type": "Via",
"street_name": "Antonio Pacinotti",
"street": "Via Antonio Pacinotti",
"address": "Via Antonio Pacinotti,4/B",
"full_address": "Via Antonio Pacinotti,4/B, Verona, VR, Veneto, 37135, Italia",
"hn": "4/B",
"postal_town1": "VERONA",
"adm_code": [
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "50137",
"adm_cod_value": "VR"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30000",
"adm_cod_value": "L781"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30021",
"adm_cod_value": "023091"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30022",
"adm_cod_value": "005"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30030",
"adm_cod_value": "11700"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30050",
"adm_cod_value": "0777000"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30060",
"adm_cod_value": "086"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30061",
"adm_cod_value": "660999"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30070",
"adm_cod_value": "ITA"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30071",
"adm_cod_value": "IT"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30072",
"adm_cod_value": "380"
},
{
"adm_cod_iso3": "ITA",
"adm_cod_type": "30114",
"adm_cod_value": "ITALIA"
}
],
"egon_code": {
"city": 38000004730,
"street": 38000073526,
"hn": 380100008326045
}
},
"smart": {
"country": "Italia",
"administrative_level": "Verona",
"city": "Verona",
"address": "Via Antonio Pacinotti,4/B",
"zipcode": "37135"
}
}
},
"quality": {
"address": {
"locality": {
"flag": "0",
"code": 0
},
"street": {
"flag": "0",
"code": 0
},
"hn": {
"flag": "0",
"code": 0
}
}
},
"system": {
"ret_code": 0,
"des_ret_code": "Ok"
}
}
Received response:
Request failed with error:
Response
Response Fields
data.address.standard.iso3
string
Country code (ISO 3166-1 alpha-3)
data.address.standard.country
string
Country description
data.address.standard.state
string
State description
data.address.standard.state_code
string
State code
data.address.standard.region
string
Region description
data.address.standard.region_code
string
Region code
data.address.standard.province
string
Province description
data.address.standard.province_code
string
Province code
data.address.standard.city
string
City description
data.address.standard.locality
string
District description
data.address.standard.locality2
string
District2 description
data.address.standard.locality3
string
District3 description
data.address.standard.zipcode
string
Zipcode
data.address.standard.full_address
string
Full address
data.address.standard.street_type
string
Dug (E.g. Via)
data.address.standard.street_name
string
Street description (E.g. Garibaldi)
data.address.standard.street
string
Dug + street description (E.g. Via Pacinotti 4b)
data.address.standard.address
string
Dug + street description + number (E.g. Via Pacinotti 4b)
data.address.standard.street_type_2
string
Dug 2 (E.g. Via)
data.address.standard.street_name_2
string
Street 2 description (E.g. Garibaldi)
data.address.standard.street_2
string
Dug 2 + Street 2 description (E.g. Via Pacinotti 4b)
data.address.standard.hn
string
House number
data.address.standard.hn_ext
string
House number other information
data.address.standard.hn_2
string
House number 2
data.address.standard.building
string
Building
data.address.standard.subbuilding
string
Subbuilding
data.address.standard.postal_town1
string
Postal area – city
data.address.standard.postal_town2
string
Postal area - locality
data.address.standard[adm_code][].adm_code_iso3
string
Country ISO code (ITA for Italy)
data.address.standard[adm_code][].adm_code_type
string
Type of code
data.address.standard[adm_code][].adm_code_value
string
Code description
data.address.standard[cnd][].province
string
Candidate: Province
data.address.standard[cnd][].city
string
Candidate: City
data.address.standard[cnd][].locality
string
Candidate: City/Town
data.address.standard[cnd][].street
string
Candidate: Street
data.address.standard[cnd][].zipcode
string
Candidate: Zipcode
data.address.standard[cnd][].street_code
integer
Candidate: Street code
data.address.standard[egon_code].city
integer
City code
data.address.standard[egon_code].street
integer
Street code
data.address.standard[egon_code].house_number
integer
House number code
data.address.smart.administrative_level
string
Administrative level
data.address.smart.city
string
City
data.address.smart.street
string
Street
data.address.smart.zipcode
string
Zipcode
quality.address.locality.flag
string
Address validation result flag (Locality)
It can have the following values:
- 0 Validated without changes.
- 1 Informational: Validated with changes
- 2/3 Not validated
quality.address.locality.code
integer
Warning/Error code (Locality)
Locality response codes:
OK with corrections/warnings – Flag = 1
- 701 - Locality candidate found
- 702 - Locality candidate found with different level
- 703 - Postcode not correct
- 704 - Different postcode for mono-postcode locality
- 705 - Different postcode for multi-postcode locality
- 706 - Different postcode for mono-postcode street
- 707 - Different postcode for multi-postcode street
- 708 - District 1 not validated
- 709 - Different words
- 710 - Locality with more words
- 711 - Locality with two less words
- 712 - Too many less words
- 713 - Postcode found
- 714 - Locality found
- 715 - Postcode different from Departement postcode
- 716 - Special Postcode
- 717 - Special Postcode
- 724 - Postcode different from postal town postcode
- 727 - Locality out of Country
- 728 - Locality out of range
- 729 - Locality found in Metropolitan City
- 734 - Locality extracted from Postcode
- 780 - Locality found with synonym
- 782 - Locality found with user synonym
- 783 - Locality found with automatic synonym
- 784 - Locality found with historic synonym
- 785 - Locality found with user synonym (type 5)
- 786 - Locality found with user synonym (type 6)
- 787 - Locality found with user synonym (type 7)
- 788 - Locality found with user synonym (type 8)
- 789 - Locality found with user synonym (type 9)
- 790 - Locality validated after post-treatment
- 791 - Locality validated with consonants candidates
- 792 - Locality validated with vowel candidates
- 793 - Locality validated with forced candidate
- 794 - Locality validated with different Province
- 798 - Country extracted from locality
- 799 - Changed Country
Errors – Flag = 2/3
- 201 - No data - locality
- 202 - Locality not found
- 203 - Ambiguous locality
- 204 - Invalid data
- 205 - Locality with words out of sequence
- 206 - Locality candidate out of sequence
- 207 - Locality with more words
- 208 - Locality with invalid elements
- 210 - Locality out of sequence
- 211 - Too many candidates for locality
- 212 - Locality not found no candidates
- 213 - Candidate with one missing word
- 214 - Too many candidates for sub-locality
- 215 - Too many candidates
- 216 - Locality out of Country
- 217 - Ambiguous Country
- 218 - Ambiguous data out of Country
- 219 - Candidate with too many missing words
- 220 - Poor information for matchcode construction
- 221 - Postal town not found
- 222 - Postal town not found
- 223 - Postal town inconsistent data
- 224 - Postcode incongruous with postal town
- 225 - Locality and postcode ambiguous
- 226 - Foreign Country not found
- 227 - Foreign locality not found
- 228 - Special postcode not correct
- 229 - Territorial level not belonging to Country
- 238 - Locality candidate extracted by phonetic
- 242 - Mandatory element
- 243 - Relative weight too low
quality.address.street.flag
string
Address validation result flag (Street)
It can have the following values:
- 0 Validated without changes.
- 1 Informational: Validated with changes
- 2/3 Not validated
quality.address.street.code
integer
Warning/Error code (Street)
Street response codes:
OK with corrections/warnings – Flag = 1
- 801 - Street candidate found
- 802 - House number not present
- 803 - Postcode corrected
- 804 - Additional information not correct
- 805 - C/O inside address
- 806 - C/O at the beginning of address
- 807 - First word not correct
- 808 - Address with two less words
- 809 - Address with different words
- 810 - Address with more words
- 811 - Wrong Street-type
- 812 - Street with too many less words
- 813 - Different postcode
- 814 - Different postcode
- 815 - Valid generic postcode
- 816 - Valid generic postcode attributed
- 817 - Address with only one word
- 818 - Only numbers in the address
- 819 - Address found with number analysis
- 820 - Numbers in the street name
- 821 - P.O box found
- 822 - Locality in extra-information
- 823 - Locality in extra-information
- 824 - Address validated from the C/O section
- 825 - Address validated from the C/O section
- 826 - Address not validated from the C/O section
- 827 - Address out of Country
- 828 - House number found
- 830 - P.O box found
- 831 - Different postcode for P.O. box
- 832 - Postcode not valid for P.O. box
- 833 - Street with one less word
- 834 - Street out of sequence
- 835 - Street with one more word
- 836 - Street with one more number
- 837 - Street with one more word
- 838 - Street validated with macro street-type
- 840 - Street not congruous with district
- 841 - District validated from street name
- 842 - Double street
- 843 - Street with corner
- 845 - Postcode valid for the street
- 846 - Valid postcode for locality
- 851 - Valid postcode – unique postcode street
- 852 - Valid postcode – multi postcode street
- 853 - Postcode extracted – unique postcode
- 855 - Postcode belonging to street
- 879 - Postcode not present for multi postcode street
- 880 - Address validated with synonym
- 881 - Address not verified for Country without street database
- 882 - Address validated with user synonym
- 883 - Address validated with automatic synonym
- 884 - Address validated with historic synonym
- 885 - Address validated with user synonym (type 5)
- 886 - Address validated with user synonym (type 6)
- 887 - Address validated with user synonym (type 7)
- 888 - Address validated with user synonym (type 8)
- 889 - Address validated with user synonym (type 9)
- 890 - Address validated after post-treatment
- 891 - Address validated with word candidates
- 892 - Address validated with consonants candidates
- 893 - Address validated with vowel candidates
- 894 - Address validated with forced candidate
- 895 - Locality extracted from address
Errors – Flag = 2/3
- 301 - No data - street
- 302 - Street not found
- 303 - Ambiguous street
- 304 - Invalid data
- 305 - Postcode not attributable for the house number
- 306 - Street with words out of sequence
- 307 - Street with more words
- 308 - Street with invalid elements
- 309 - Street with first word not found
- 310 - Street not extracted
- 311 - Too many candidates for street
- 312 - Street candidates not found
- 313 - House number not valid
- 314 - Too many Postcode ranges
- 315 - Too many house numbers
- 316 - Extraurban street not valid
- 317 - Extraurban street not valid
- 318 - Extraurban street not valid
- 319 - Extraurban street not valid
- 320 - Street with too many commas
- 321 - Street with comma and separated house number
- 322 - Two street-type found
- 323 - Address mask not found
- 324 - House number not found
- 325 - Ambiguous street
- 326 - Ambiguous street and postcode
- 327 - House number not found for multi-postcode street
- 328 - Street not recognizable
- 329 - Postcode not valid
- 330 - Street-type not valid
- 331 - Candidate with too many less words
- 332 - Street not verified caused by locality error
- 333 - Double C/O
- 334 - Mask error
- 335 - Candidates not valid
- 336 - Address equal to locality
- 337 - Address not valid
- 338 - Candidates not valid
- 339 - Foreign address not found
- 340 - Too many particular words in the address
- 341 - Second street wrong
- 342 - Mandatory element
- 343 - Relative weight too low
- 344 - Exponent not found in the range
- 345 - Range not found for the street
- 399 - Street forced by user
- 997 - Street not elaborated caused by Country error
- 999 - Logic error
quality.address.house_number.flag
string
Address validation result flag (House number)
It can have the following values:
- 0 Validated without changes.
- 1 Informational: Validated with changes
- 2/3 Not validated
quality.address.house_number.code
integer
Warning/Error code (House number)
House number response codes:
OK with corrections/warnings – Flag = 1
- 502 - House Number not certified
- 503 - Certified house number (numeric part only)
- 504 - House number code not found
- 505 - House number code reassigned
- 506 - House number not certified (numeric part only)
- 590 - Certification not active
Errors – Flag = 2/3
- 501 - House number not found
- 598 - House number not present in input
- 599 - House number not verified caused by street error
system.ret_code
integer
System code:
- 0 = no blocking error
- <> 0 blocking error code
system.des_ret_code
string
Error description
Validation API V4 Emails
requires authentication
Email normalization. Maximum of 5 emails in input.
Example request:
curl --request POST \
"https://api.address4.com/v4/validation/emails" \
--header "Authorization: Bearer {YOUR_APP_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"par\": {
\"iso3\": \"ITA\"
},
\"data\": {
\"emails\": [
{
\"email\": \"mario.rossi@gmail.com\"
}
]
}
}"
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.address4.com/v4/validation/emails',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_APP_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => \Symfony\Component\VarExporter\Internal\Hydrator::hydrate(
$o = [
clone (\Symfony\Component\VarExporter\Internal\Registry::$prototypes['stdClass'] ?? \Symfony\Component\VarExporter\Internal\Registry::p('stdClass')),
],
null,
[
'stdClass' => [
'email' => [
'mario.rossi@gmail.com',
],
],
],
[
'par' => [
'iso3' => 'ITA',
],
'data' => [
'emails' => [
$o[0],
],
],
],
[]
),
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
"https://api.address4.com/v4/validation/emails"
);
const headers = {
"Authorization": "Bearer {YOUR_APP_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"par": {
"iso3": "ITA"
},
"data": {
"emails": [
{
"email": "mario.rossi@gmail.com"
}
]
}
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
{
"data": {
"emails": [
{
"email": "mario.rossi@gmail.com"
}
]
},
"quality": {
"emails": [
{
"email1": {
"flag": "1",
"code": 991
}
}
]
},
"system": {
"ret_code": 0,
"des_ret_code": "Ok"
}
}
Received response:
Request failed with error:
Response
Response Fields
data.emails[].email
string
quality.emails.email[i].flag
string
i must be between 1 and 5
Signal level. It can have the following values:
- 0 Validated without changes.
- 1 Informational: Validated with changes
- 2/3 Not validated
quality.emails.email[i].code
integer
Signal code
system.ret_code
integer
System code:
- 0 = no blocking error
- <> 0 blocking error code
system.des_ret_code
string
Error description
Response errors:
OK with corrections/warnings – Flag = 1
- 463 - Double points
- 464 - IP Formatted email
- 465 - Points found
- 466 - Valid Domain
- 467 - Email with generic National first level domain
- 468 - Email with national first level domain
- 469 - Email with official domain
- 980 - First level domain not certified
- 981 - Forced @
- 982 - Substitution @
- 983 - Email modified
- 984 - Domain modified
- 985 - Fake email
- 986 - Email starting with special characters
- 987 - URL in email
- 988 - Too many emails
- 989 - Additional information found
- 991 - Certified domain
Errors – Flag = 2/3
- 460 - Format not valid
- 461 - Email format not recognized
- 462 - Unknown domain
- 470 - Not valid domain
- 401 - Email not present
- 402 - Wrong email format
- 428 - Invalid characters
- 443 - Wrong domain
- 454 - Wrong I° level domain
- 455 - Wrong domain
- 456 - @ not present
- 457 - II° level domain not present
- 458 - Domain not certified