Autocomplete

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

Step 1.

Request

GET https://api.getaddress.io/autocomplete/{term}?api-key={your-api-key}

Response

{
    "suggestions":
    [
        {
            "address": "200 GEORGE ST, LAUNCESTON TAS 7250",
            "url": "/get/GATAS702238303",
            "id": "GATAS702238303"
        },
        {
            "address": "200 GEORGE ST, BATHURST NSW 2795",
            "url": "/get/GANSW704039848",
            "id": "GANSW704039848"
        },
        {
            "address": "200 GEORGE ST, EAST MAITLAND NSW 2323",
            "url": "/get/GANSW704640936",
            "id": "GANSW704640936"
        },
        {
            "address": "200 GEORGE ST, QUEENS PARK WA 6107",
            "url": "/get/GAWA_163047704",
            "id": "GAWA_163047704"
        },
        {
            "address": "UNIT 2 200 GEORGE ST, WINDSOR NSW 2756",
            "url": "/get/GANSW712891236",
            "id": "GANSW712891236"
        }
    ]
}

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={your-api-key}

Authentication

Your API key goes in the api-key query parameter, as above. It is the only place the key is read from: an api-key header, Basic auth or a bearer token is not accepted.

Google Places fallback

When the Google Places fallback is switched on for your subscription, a request made with a domain token that finds no suggestions also returns your own Google API key, so the JavaScript Autocomplete can search Google itself. It is never returned with suggestions, and never to an API key.

{
    "suggestions": [],
    "fallback":
    {
        "provider": "google_places",
        "key": "{your-google-api-key}"
    }
}

Filter

A filter limits results to specific criteria.

Request

{
    "filter":
    {
        "state":"{state abbreviation, e.g. NSW}",
        "locality":"{locality / suburb}",
        "postcode":"{4-digit postcode}",
        "radius":{
            "km":"{max distance from lat/long in kilometres}",
            "longitude":{longitude},
            "latitude":{latitude}
        }
    }
}

Example

Filtering 'state' to 'VIC' will only return addresses in Victoria

Request

{
    "filter":
    {
        "state":"VIC"
    }
}

Location

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

Request

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

Example

Searching for 'Stirling Street' without location

Response

{
    "suggestions":
    [
        {
            "address": "26 STIRLING ST, FOOTSCRAY VIC 3011",
            "url": "/get/GAVIC419734226",
            "id": "GAVIC419734226"
        },
        {
            "address": "CAMPUS PERTH 80 STIRLING ST, PERTH WA 6000",
            "url": "/get/GAWA_146657699",
            "id": "GAWA_146657699"
        }
    ]
}

Example

Searching for 'Stirling Street' with location set in Perth.

Request

{
    "location":
    {
        "latitude":-31.9505,
        "longitude":115.8605
    }
}

Response

{
    "suggestions":
    [
        {
            "address": "CAMPUS PERTH 80 STIRLING ST, PERTH WA 6000",
            "url": "/get/GAWA_146657699",
            "id": "GAWA_146657699"
        },
        {
            "address": "UNIT 4 269 STIRLING ST, PERTH WA 6000",
            "url": "/get/GAWA_148017035",
            "id": "GAWA_148017035"
        }
    ]
}

Location from an IP address

If you don't send a location, Autocomplete can work one out from your end user's IP address and prefer suggestions near them. This matters in Australia: '12 George St' is a real address in Sydney, Parramatta, Brisbane and Launceston, and without a location all four compete for the same six slots.

There is nothing to switch on, and it depends on which credential you use:

Domain token — the request comes from your visitor's browser, so their address is already known and used automatically. Send nothing.
API key — the request comes from your server, so the address we see is your server's and is never used. Pass your end user's address as ip_address if you want this behaviour.

Request

{
    "ip_address":"1.128.0.1"
}

Worth knowing:

It is a preference, never a filter. Nearby matches come first and the remaining slots are filled from the whole country, so an address far from your user is still found.
Anything you send yourself wins. A location, or a filter on state, locality, postcode or radius, turns it off for that request — you know where to look, and we don't second-guess you.
An IP address places someone in a city at best, and mobile networks regularly place them in the wrong one. Fixes outside Australia, and fixes too coarse to name a region, are ignored rather than guessed at.
ip_address is read from the POST body only — never from the query string, which would leave your user's address in server and proxy logs along the way.
The look-up runs against a database on our own servers. The address is used to order that one response and nothing else: never stored, never logged, never returned to you, and never sent to a third party.

This product includes GeoLite2 data created by MaxMind, available from maxmind.com.

Other Parameters

Property	Default	Description	Type
top	6	Sets the number of suggestions to retrieve (max 6)	Text
template	{formatted_address}	Suggestion Text template. Available fields: {formatted_address}, {locality_name}, {locality}, {suburb}, {state}, {postcode} `{field,prefix,suffix}` wraps a non-empty field with the given prefix and suffix, e.g. `{locality, (,)}`.	Text
ip_address	None	Your end user's IP address, used to prefer suggestions near them. POST body only, and read only on an API-key request — see Location from an IP address above.	Text

Usage

Autocomplete queries are rate limited but do not increase your usage.
Resolving an autocomplete suggestion with the Get API counts as 1 look-up.

Domain Tokens

To avoid exposing your API key in browser code, Domain Tokens can be used in place of your API key. A Domain Token is generated for one domain and works on that domain and its sub-domains.

A Domain Token can only be used for address and place look-ups — /autocomplete, /get, /validate, /distance, /location, /get-location, /nearest-location and /typeahead. It cannot read your usage, so it carries none of the access your API key does. A revoked Domain Token stops working within a minute.

Each token is throttled per visitor IP address: 60 look-ups per minute by default, and the limit can be set per token (1–10,000 look-ups over a window of 1–60 minutes). Requests over the limit get 429 with a Retry-After header. There is a second ceiling on the token's total traffic across all visitors, so a token being used somewhere other than your site is throttled even when every request arrives from a different address.

Look-ups made with a Domain Token count against your plan's allowance exactly as look-ups made with your API key do.

A Domain Token is also what carries the free Google Places fallback: with it switched on, an autocomplete that finds nothing hands the widget your own Google API key.

What a Domain Token is, and what it isn't. It keeps your API key out of your page source, and it makes a token copied out of your page close to worthless: it works only on your domain, only for look-ups, and only at the rate you set. It is not a secret — you publish it in your page — and the domain check reads request headers, which a determined caller can set to anything. The throttle is the protection; set it no higher than your address form actually needs.

<script>
    async function getAddress() {
        return await fetch("https://api.getaddress.io/get/GANSW718642855?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.