NAV -image
href="#" data-language-name="bash">bash href="#" data-language-name="php">php href="#" data-language-name="javascript">javascript

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

Authentication

The Address4 API uses API keys to authenticate requests. 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}

Services

Services

requires authentication

Example request:

curl -X GET \
    -G "https://api.address4.com/v2/services?lang=en" \
    -H "Authorization: Bearer {YOUR_APP_KEY}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.address4.com/v2/services',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_APP_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'lang'=> 'en',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.address4.com/v2/services"
);

let params = {
    "lang": "en",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let 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):

[
    {
        "id": 2,
        "type": "Online",
        "slug": "AddressValidationOnline",
        "name": "Address Validation Online"
    }
]

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:\/\/api-address4.pur4u.ro\/docs for details."
    }
}

Request   

GET v2/services

Query Parameters

lang  string optional  
With this parameter we set in which language we want the names of the services.

Country

requires authentication

Validation and suggestion requests are restricted to the countries that are received in this endpoint. They can be changed in section Account > Services

Example request:

curl -X GET \
    -G "https://api.address4.com/v2/services/country" \
    -H "Authorization: Bearer {YOUR_APP_KEY}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.address4.com/v2/services/country',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_APP_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.address4.com/v2/services/country"
);

let 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_id": 25000000001,
        "country_name": "France",
        "iso3": "FRA"
    },
    {
        "country_id": 27600000001,
        "country_name": "Germany",
        "iso3": "DEU"
    }
]

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:\/\/api-address4.pur4u.ro\/docs for details."
    }
}

Request   

GET v2/services/country

Statistics

v2/stats

requires authentication

Example request:

curl -X GET \
    -G "https://api.address4.com/v2/stats?interval=month&start=2017-03-15+12%3A00%3A00&endDate=2018-03-15+12%3A00%3A00" \
    -H "Authorization: Bearer {YOUR_APP_KEY}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.address4.com/v2/stats',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_APP_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'interval'=> 'month',
            'start'=> '2017-03-15 12:00:00',
            'endDate'=> '2018-03-15 12:00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.address4.com/v2/stats"
);

let params = {
    "interval": "month",
    "start": "2017-03-15 12:00:00",
    "endDate": "2018-03-15 12:00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let 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):

{
    "Total": {
        "2018-03-01 00:00:00": 0,
        "2018-04-01 00:00:00": 0,
        "2018-05-01 00:00:00": 0,
        "2018-06-01 00:00:00": 0,
        "2018-07-01 00:00:00": 0,
        "2018-08-01 00:00:00": 0,
        "2018-09-01 00:00:00": 0,
        "2018-10-01 00:00:00": 0,
        "2018-11-01 00:00:00": 0,
        "2018-12-01 00:00:00": 0,
        "2019-01-01 00:00:00": 0,
        "2019-02-01 00:00:00": 0,
        "2019-03-01 00:00:00": 0,
        "2019-04-01 00:00:00": 0,
        "2019-05-01 00:00:00": 0,
        "2019-06-01 00:00:00": 0,
        "2019-07-01 00:00:00": 0,
        "2019-08-01 00:00:00": 0,
        "2019-09-01 00:00:00": 0,
        "2019-10-01 00:00:00": 0,
        "2019-11-01 00:00:00": 0,
        "2019-12-01 00:00:00": 0,
        "2020-01-01 00:00:00": 0,
        "2020-02-01 00:00:00": 0,
        "2020-03-01 00:00:00": 0,
        "2020-04-01 00:00:00": 0,
        "2020-05-01 00:00:00": 0,
        "2020-06-01 00:00:00": 0,
        "2020-07-01 00:00:00": 0,
        "2020-08-01 00:00:00": 0,
        "2020-09-01 00:00:00": 0,
        "2020-10-01 00:00:00": 44,
        "2020-11-01 00:00:00": 70,
        "2020-12-01 00:00:00": 66,
        "2021-01-01 00:00:00": 13
    },
    "Suggest": {
        "2018-03-01 00:00:00": 0,
        "2018-04-01 00:00:00": 0,
        "2018-05-01 00:00:00": 0,
        "2018-06-01 00:00:00": 0,
        "2018-07-01 00:00:00": 0,
        "2018-08-01 00:00:00": 0,
        "2018-09-01 00:00:00": 0,
        "2018-10-01 00:00:00": 0,
        "2018-11-01 00:00:00": 0,
        "2018-12-01 00:00:00": 0,
        "2019-01-01 00:00:00": 0,
        "2019-02-01 00:00:00": 0,
        "2019-03-01 00:00:00": 0,
        "2019-04-01 00:00:00": 0,
        "2019-05-01 00:00:00": 0,
        "2019-06-01 00:00:00": 0,
        "2019-07-01 00:00:00": 0,
        "2019-08-01 00:00:00": 0,
        "2019-09-01 00:00:00": 0,
        "2019-10-01 00:00:00": 0,
        "2019-11-01 00:00:00": 0,
        "2019-12-01 00:00:00": 0,
        "2020-01-01 00:00:00": 0,
        "2020-02-01 00:00:00": 0,
        "2020-03-01 00:00:00": 0,
        "2020-04-01 00:00:00": 0,
        "2020-05-01 00:00:00": 0,
        "2020-06-01 00:00:00": 0,
        "2020-07-01 00:00:00": 0,
        "2020-08-01 00:00:00": 0,
        "2020-09-01 00:00:00": 0,
        "2020-10-01 00:00:00": 43,
        "2020-11-01 00:00:00": 12,
        "2020-12-01 00:00:00": 3,
        "2021-01-01 00:00:00": 5
    },
    "Validation": {
        "2018-03-01 00:00:00": 0,
        "2018-04-01 00:00:00": 0,
        "2018-05-01 00:00:00": 0,
        "2018-06-01 00:00:00": 0,
        "2018-07-01 00:00:00": 0,
        "2018-08-01 00:00:00": 0,
        "2018-09-01 00:00:00": 0,
        "2018-10-01 00:00:00": 0,
        "2018-11-01 00:00:00": 0,
        "2018-12-01 00:00:00": 0,
        "2019-01-01 00:00:00": 0,
        "2019-02-01 00:00:00": 0,
        "2019-03-01 00:00:00": 0,
        "2019-04-01 00:00:00": 0,
        "2019-05-01 00:00:00": 0,
        "2019-06-01 00:00:00": 0,
        "2019-07-01 00:00:00": 0,
        "2019-08-01 00:00:00": 0,
        "2019-09-01 00:00:00": 0,
        "2019-10-01 00:00:00": 0,
        "2019-11-01 00:00:00": 0,
        "2019-12-01 00:00:00": 0,
        "2020-01-01 00:00:00": 0,
        "2020-02-01 00:00:00": 0,
        "2020-03-01 00:00:00": 0,
        "2020-04-01 00:00:00": 0,
        "2020-05-01 00:00:00": 0,
        "2020-06-01 00:00:00": 0,
        "2020-07-01 00:00:00": 0,
        "2020-08-01 00:00:00": 0,
        "2020-09-01 00:00:00": 0,
        "2020-10-01 00:00:00": 1,
        "2020-11-01 00:00:00": 58,
        "2020-12-01 00:00:00": 63,
        "2021-01-01 00:00:00": 8
    }
}

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:\/\/api-address4.pur4u.ro\/docs for details."
    }
}

Request   

GET v2/stats

Query Parameters

interval  string optional  
These are the interval of statistics selection. The accepted units for calendar intervals are: `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`.

start  string optional  
This is the start date of statistics and it accepts a form like `Y-m-d H:i:s`.

endDate  string optional  
This is the end date of the statistics and it accepts a format like `Y-m-d H:i:s`.

Status

v2/status

requires authentication

Example request:

curl -X GET \
    -G "https://api.address4.com/v2/status" \
    -H "Authorization: Bearer {YOUR_APP_KEY}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.address4.com/v2/status',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_APP_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.address4.com/v2/status"
);

let 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):

{
    "credits": "11628275.25",
    "used": "255.50"
}

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:\/\/api-address4.pur4u.ro\/docs for details."
    }
}

Request   

GET v2/status

Suggest

v2/suggest/{type}

requires authentication

Example request:

curl -X GET \
    -G "https://api.address4.com/v2/suggest/city?query=via+pacinotti+4b" \
    -H "Authorization: Bearer {YOUR_APP_KEY}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.address4.com/v2/suggest/city',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_APP_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'query'=> 'via pacinotti 4b',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.address4.com/v2/suggest/city"
);

let params = {
    "query": "via pacinotti 4b",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let 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": 38000005662,
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Toscana",
        "region_id": 38000000010,
        "province": "Lucca",
        "province_id": 38000000064,
        "province_code": "LU",
        "city": "Viareggio",
        "city_id": 38000005662,
        "zipcode": "55049",
        "description": "Viareggio (LU) - Italia",
        "description_short": "Viareggio"
    },
    {
        "iso3": "ITA",
        "level": "city",
        "id": 38000005350,
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Lombardia",
        "region_id": 38000000004,
        "province": "Mantova",
        "province_id": 38000000068,
        "province_code": "MN",
        "city": "Viadana",
        "city_id": 38000005350,
        "zipcode": "46019",
        "description": "Viadana (MN) - Italia",
        "description_short": "Viadana"
    },
    {
        "iso3": "ITA",
        "level": "city",
        "id": 38000007996,
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Sicilia",
        "region_id": 38000000020,
        "province": "Catania",
        "province_id": 38000000048,
        "province_code": "CT",
        "city": "Viagrande",
        "city_id": 38000007996,
        "zipcode": "95029",
        "description": "Viagrande (CT) - Italia",
        "description_short": "Viagrande"
    },
    {
        "iso3": "ITA",
        "level": "city",
        "id": 38000005194,
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Emilia-Romagna",
        "region_id": 38000000009,
        "province": "Reggio Emilia",
        "province_id": 38000000090,
        "province_code": "RE",
        "city": "Viano",
        "city_id": 38000005194,
        "zipcode": "42030",
        "description": "Viano (RE) - Italia",
        "description_short": "Viano"
    },
    {
        "iso3": "ITA",
        "level": "city",
        "id": 38000003189,
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Lombardia",
        "region_id": 38000000004,
        "province": "Bergamo",
        "province_id": 38000000032,
        "province_code": "BG",
        "city": "Viadanica",
        "city_id": 38000003189,
        "zipcode": "24060",
        "description": "Viadanica (BG) - Italia",
        "description_short": "Viadanica"
    },
    {
        "iso3": "ITA",
        "level": "city",
        "id": 38000001825,
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Piemonte",
        "region_id": 38000000002,
        "province": "Asti",
        "province_id": 38000000029,
        "province_code": "AT",
        "city": "Viarigi",
        "city_id": 38000001825,
        "zipcode": "14030",
        "description": "Viarigi (AT) - Italia",
        "description_short": "Viarigi"
    },
    {
        "iso3": "ITA",
        "level": "city",
        "id": 38000001264,
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Piemonte",
        "region_id": 38000000002,
        "province": "Torino",
        "province_id": 38000000105,
        "province_code": "TO",
        "city": "Vialfrè",
        "city_id": 38000001264,
        "zipcode": "10090",
        "description": "Vialfrè (TO) - Italia",
        "description_short": "Vialfrè"
    },
    {
        "iso3": "ITA",
        "level": "city",
        "id": 38000001780,
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Piemonte",
        "region_id": 38000000002,
        "province": "Asti",
        "province_id": 38000000029,
        "province_code": "AT",
        "city": "Viale",
        "city_id": 38000001780,
        "zipcode": "14010",
        "description": "Viale (AT) - Italia",
        "description_short": "Viale"
    },
    {
        "iso3": "ITA",
        "level": "city",
        "id": 38000003622,
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Lombardia",
        "region_id": 38000000004,
        "province": "Pavia",
        "province_id": 38000000086,
        "province_code": "PV",
        "city": "Sant'Alessio con Vialone",
        "city_id": 38000003622,
        "zipcode": "27016",
        "description": "Sant'Alessio con Vialone (PV) - Italia",
        "description_short": "Sant'Alessio con Vialone"
    }
]

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:\/\/api-address4.pur4u.ro\/docs for details."
    }
}

Request   

GET v2/suggest/{type}

URL Parameters

type  string  
Suggest services are available. Supported values are `country`, `state`, `region`, `province`, `city`, `district1`, `district2`, `district3` or `street`.

Query Parameters

query  string  
The search text which is the basis of the query.

enabled_levels  string optional  
Get the sublevels presence.

output  string optional  
Force the output type for description. Can be: `nat` (native), `lat` (latinized), `int` (international).

restrict_id  string optional  
Search filter identification.

restrict_level  integer optional  
Search filter level. Cound be: `country`, `state`, `region`, `province`, `city`, `district1`, `district2`.

Validation

v2/validation

requires authentication

Example request:

curl -X GET \
    -G "https://api.address4.com/v2/validation?city=firenze&country=ITA&street=via+antonio+pacinotti+4" \
    -H "Authorization: Bearer {YOUR_APP_KEY}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.address4.com/v2/validation',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_APP_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'city'=> 'firenze',
            'country'=> 'ITA',
            'street'=> 'via antonio pacinotti 4',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.address4.com/v2/validation"
);

let params = {
    "city": "firenze",
    "country": "ITA",
    "street": "via antonio pacinotti 4",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let 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):

{
    "seg": {
        "error_level": 0,
        "error_code": 0,
        "error_desc": "Ok"
    },
    "result": [
        {
            "address": {
                "country": "Italia",
                "region": "Toscana",
                "county": "Firenze",
                "city": "Firenze",
                "street": "Via Antonio Pacinotti",
                "house_number": "4",
                "zipcode": "50131",
                "additional_data": {
                    "county": "FI"
                },
                "full_address": "Via Antonio Pacinotti,4, Firenze, FI, Toscana, Italia",
                "full_street": "Via Antonio Pacinotti,4"
            },
            "country_code": "ITA"
        }
    ]
}

Example response (200, Validation is incomplete):

{
    "seg": {
        "error_level": 1,
        "error_code": 801,
        "error_desc": "Candidato strada con parole in meno"
    },
    "result": [
        {
            "address": {
                "country": "Italia",
                "region": "Veneto",
                "county": "Verona",
                "city": "Verona",
                "street": "Via Antonio Pacinotti",
                "house_number": "4\/B",
                "zipcode": "37135",
                "additional_data": {
                    "county": "VR"
                },
                "full_address": "Via Antonio Pacinotti,4\/B, Verona, VR, Veneto, Italia",
                "full_street": "Via Antonio Pacinotti,4\/B"
            },
            "country_code": "ITA"
        }
    ]
}

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:\/\/api-address4.pur4u.ro\/docs for details."
    }
}

Request   

GET v2/validation

Query Parameters

city  string optional  
City.

country  string  
Country ISO 3.

province  string optional  
Province.

district1  string optional  
District.

house_number  integer optional  
House number (contains house number detail too).

location_id  string optional  
Code uniquely identifying a physical location.

postalcode  string optional  
Zip code.

state  string optional  
State.

street  string optional  
Street.

output  string optional  
Force the output type for description. Can be: `nat` (native), `lat` (latinized), `int` (international).

upper  string optional  
Type format output forced UPPER description (1 to force upper).