MENU navbar-image

Introduction

This is the Egon API documentation.
This documentation aims to provide all the information you need to work with our API.

Base URL

https://api.egon.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 Egon 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

Suggest API
Example request:
curl --request GET \
    --get "https://api.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

Example response (4xx, Bad Request):


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

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

Country API
Example request:
curl --request GET \
    --get "https://api.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

Request   

GET v3/suggest/country

Query Parameters

query  string  

Query string.

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.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

Request   

GET v3/suggest/state

Query Parameters

query  string  

Query string.

iso3  string  

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

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.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

Request   

GET v3/suggest/region

Query Parameters

query  string  

Query string.

iso3  string  

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

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.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

Request   

GET v3/suggest/province

Query Parameters

query  string  

Query string.

iso3  string  

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

restrict_id  integer optional  

ID of the territorial level.
Used for filtering the research by a certain territorial level.

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

City API
Example request:
curl --request GET \
    --get "https://api.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

Request   

GET v3/suggest/city

Query Parameters

query  string  

Query string.

iso3  string  

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

restrict_id  integer optional  

ID of the territorial level.
Used for filtering the research by a certain territorial level.

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.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

Request   

GET v3/suggest/district1

Query Parameters

query  string  

Query string.

iso3  string  

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

restrict_id  integer optional  

ID of the territorial level.
Used for filtering the research by a certain territorial level.

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

Suggest API - via address
Example request:
curl --request GET \
    --get "https://api.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

Example response (4xx, Bad Request):


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

Request   

GET v3/suggest/street

Query Parameters

query  string  

Query string.

iso3  string  

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

restrict_id  integer  

ID of the city level.
Used for filtering the research by a certain territorial level.

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.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

Request   

GET v3/suggest/zipcode

Query Parameters

query  string  

Query string.

iso3  string  

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

zip_level  string optional  

Extraction level. It can be set to:
- L = Candidates at locality level
- S = Candidates at street level - used in GBR / IRL / NLD / JPN
Default: L.

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.

Validation API
Example request:
curl --request GET \
    --get "https://api.egon.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.egon.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.egon.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.egon.com/docs for details."
    }
}
 

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