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

This API is authenticated 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 V3

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"

$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',
        ],
    ]
);
$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",
};

fetch(url, {
    method: "GET",
    headers,
}).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 (4xx, Bad Request):


{
    "error": {
        "code": 400,
        "message": "Missing the 'query'."
    }
}

Received response:

Request failed with error:

Request

GET v3/suggest/address

Query Parameters

query string

Query string.

restrict_id integer optional

ID of the territorial level.
Used for filtering the research by a certain territorial level.
It must be combined with restrict_level.

restrict_level string optional

Territorial level of restriction.
Used for filtering the research by a certain territorial level.
It must be combined with restrict_id.
Allowed values: state, region, province, city, district1.

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"

$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',
        ],
    ]
);
$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",
};

fetch(url, {
    method: "GET",
    headers,
}).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"

$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',
        ],
    ]
);
$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",
};

fetch(url, {
    method: "GET",
    headers,
}).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"

$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',
        ],
    ]
);
$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",
};

fetch(url, {
    method: "GET",
    headers,
}).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"

$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',
        ],
    ]
);
$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",
};

fetch(url, {
    method: "GET",
    headers,
}).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"

$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',
        ],
    ]
);
$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",
};

fetch(url, {
    method: "GET",
    headers,
}).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"

$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',
        ],
    ]
);
$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",
};

fetch(url, {
    method: "GET",
    headers,
}).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"

$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',
        ],
    ]
);
$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",
};

fetch(url, {
    method: "GET",
    headers,
}).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 (4xx, 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"

$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',
        ],
    ]
);
$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",
};

fetch(url, {
    method: "GET",
    headers,
}).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

Validation API V3

requires authentication

This section describes how to use the Validation API V3.

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:

Request

GET v3/validation

Query Parameters

country_code string

Country code (ISO 3166-1 alpha-3 or ISO 3166-1 alpha-2).

country string optional

Country. Mandatory if country_code is not valued.

adm_level1 string optional

Administrative area level 1 (state or region).

adm_level2 string optional

Administrative area level 2 (province or department or county).

city string optional

City.

sub_locality1 string optional

Locality or City district or Village.

sub_locality2 string optional

Locality or City district or Village.

addr1 string optional

Address. As an alternative to street_name + house_nr + house_nr_ext.

addr2 string optional

Secondary address.

street_name string optional

Street name.

house_nr string optional

House number (including exponents). In addition to street_name as an alternative to addr1.

house_nr_ext string optional

House number extension (additional infos). In addition to street_name and house_nr as an alternative to addr1.

zipcode string optional

Postal code.

lng_output string optional

Output Language. By default the input language is preserved, but it can be set to:
- NAT (native)
- TRA (translittered)
- INT (international/english).

fmt_output string optional

Output format. By default the output format is Capitalized, but it can be set to:
- C (capitalized case)
- M (upper case)
- T (upper case without accents).

egon_key_code string optional

Univocal and permanent code identifying a physical location. It can identify a locality or an address.

single_line string optional

Complete address on single line. As an alternative to addr1 or street_name + house_nr + house_nr_ext.

po_box string optional

PO Box.

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.adm_level_main 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.sub_locality1 string

Sub-locality District level 1. Not every Country exhibits this territorial level.

output_complete.sub_locality2 string

Sub-locality District level 2. Not every Country exhibits this territorial level.

output_complete.sub_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.house_number string

House number + Exponent.

output_complete.house_number_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