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