Loading...

Autocomplete

The Autocomplete API suggests partial address results for a given term.

Step 1.

Request

GET POST https://api.getAddress.io/autocomplete/{term}?api-key={api-key}

Response

{
    "suggestions": 
    [
        {
            "address": "Westminster Gallery, Westminster Central Hall, Westminster, London",
            "url": "/get/NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1",
            "id": "NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1"
        },
        {
            "address": "Westminster School Lawrence Hall, Greycoat Street, Westminster, London",
            "url": "/get/MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0",
            "id": "MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0"
        },
        {
            "address": "Knight Frank Victoria & Westminster, 51 Victoria Street, Westminster, London",
            "url": "/get/ZDNhNGJhMmY5YjU0ZWRlIDUxMTQ2ODU2",
            "id": "ZDNhNGJhMmY5YjU0ZWRlIDUxMTQ2ODU2"
        },
        {
            "address": "Easy R M S, 8 Westminster City Hall, Westminster, London",
            "url": "/get/NWRmYWUxMWY2N2E0NGQyIDUxMDM5NDcx",
            "id": "NWRmYWUxMWY2N2E0NGQyIDUxMDM5NDcx"
        },
        {
            "address": "Howick Place Westminster, 7 Howick Place, Westminster, London",
            "url": "/get/ZGQyYTFjMGI0YTkzZjRjIDUxMTE5NDg3",
            "id": "ZGQyYTFjMGI0YTkzZjRjIDUxMTE5NDg3"
        }
    ]
}
Step 2.

The selected 'Id' is passed to the 'Get' API to return the full address.

Request

GET https://api.getAddress.io/get/{id}?api-key={api-key}

Response

{
    "postcode": "NN1 3ER",
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "formatted_address": [
        "10 Watkin Terrace",
        "",
        "",
        "Northampton",
        "Northamptonshire"
     ],
    "thoroughfare":  "Watkin Terrace",
    "building_name":  "",
    "sub_building_name":  "",
    "sub_building_number":  "",
    "building_number":  "10",
    "line_1":  "10 Watkin Terrace",
    "line_2":  "",
    "line_3":  "",
    "line_4":  "",
    "locality":  "",
    "town_or_city":  "Northampton",
    "county":  "Northamptonshire",
    "district":  "Northampton",
    "country":  "England"
    "residential":  true
}

Filter

A filter limits results to specific criteria.

Request

{
    "filter":
    {
        "county":"{county name}",
        "country":"{country name}",
        "locality":"{locality}",
        "district":"{district name}",
        "town_or_city":"{town or city name}",
        "postcode":"{postcode}",
        "residential":{true or false}
        "radius":{
            "km":"{max distance from lat/long in kilometres}",
            "longitude":{longitude},
            "latitude":{latitude}
        }
    }
}
Example

Filtering 'town_or_city' to 'London' will only return addresses in London

Request

{
    "filter":
    {
        "town_or_city":"London"
    }
}

Location

Instructs the Autocomplete service to prefer suggestions closer to the location.

Request

{
    "location":
    {
        "latitude":{latitude},
        "longitude":{longitude}
    }
}
Example

Searching for 'Homestead Road' without location

Response

{
    "suggestions": 
    [
        {
            "address": "1a Homestead Road, London",
            "url": "/get/NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1",
            "id": "NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1"
        },
        {
            "address": "1b Homestead Road, London",
            "url": "/get/MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0",
            "id": "MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0"
        }
    ]
}
Example

Searching for 'Homestead Road' with location set in Sheffield.

Request

{
    "location":
    {
        "latitude":53.42416763305664,
        "longitude":-1.45220148563385
    }
}

Response

{
    "suggestions": 
    [
        {
            "address": "2 Homestead Road, Sheffield, South Yorkshire",
            "url": "/get/YzUyZDZlOWIyZTUyODdkIDczMTQzMjggNzMyODU3YTM5ZDc4OTE5",
            "id": "YzUyZDZlOWIyZTUyODdkIDczMTQzMjggNzMyODU3YTM5ZDc4OTE5"
        },
        {
            "address": "4 Homestead Road, Sheffield, South Yorkshire",
            "url": "/get/YzRmNDMxMjEwZTMzZmQ5IDczMTQzMjUgNzMyODU3YTM5ZDc4OTE5",
            "id": "YzRmNDMxMjEwZTMzZmQ5IDczMTQzMjUgNzMyODU3YTM5ZDc4OTE5"
        }
    ]
}

Other Parameters

Property Default Description Type
top 6 Sets the number of suggestions to retrieve (max 6) Text
all true Returns all suggestions when search term contains a postcode* true/false
template {formatted_address}{postcode,, }{postcode} Suggestion Text template. Available fields:
{formatted_address}, {line_1}, {line_2}, {line_3}, {line_4}, {town_or_city}, {locality}, {county}, {country}, {outcode}, {postcode} 		Text
show-postcode false When true, the postcode is always shown in the suggestions* true/false

Usage

  • Queries are rate limited but do not increase your usage*.
  • Resolving an autocomplete suggestion counts as 1 look-up.
  • *Queries with only postcode and parameter:all=true count as 1 look-up.
  • *Queries with parameter:show-postcode=true count as 1 look-up.

Domain Tokens

To avoid exposing your API key in browser code, Domain Tokens can used in place of your API key.
Domain Tokens can be generated for a specific domain and it's sub-domains. They can also limit the number of look-ups per minute for an IP address. 

<script>
    async function getAddress() {
        return await fetch("https://api.getAddress.io/get/123?api-key=dtoken_hEDzcyiWMI1eXXXX");
    }
</script>

Rate Limiting

Your subscription's plan will limit the number of requests per 5 minute span. Exceeding your plan's rate limit will return a HTTP 429 response.
The Retry-After HTTP header contains the number of seconds until a successful retry can be made.

Top