Loading...
Sign in to see the examples with your own API key.

Typeahead

The Typeahead API helps people complete forms by completing a partly typed suburb, postcode, street or state. It returns plain values, not addresses.

Request

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

Request

GET https://api.getaddress.io/typeahead/bon?api-key={your-api-key}

Response

[
    "BONDI JUNCTION",
    "BONDI BEACH",
    "BONDI",
    "BONGAREE",
    "BONBEACH",
    "BONNYRIGG"
]

Without a search, every field is completed and no field comes before another. Within a field, suburbs come bigger first; postcodes and streets in order.

Search

Restricts the search to specific fields. Send it as the body of a POST.

All possible search fields:

{
    "search": ["locality", "postcode", "street", "state"]
}
Field Completes Example
locality Suburbs, as G-NAF names them. A name held in two states is one value. "st kil" → "ST KILDA", "ST KILDA EAST", "ST KILDA WEST"
postcode Four-digit postcodes. "08" → "0800", "0810", "0812"
street Streets, name and type — "RAMSAY" completes "RAMSAY LANE", "RAMSAY ROAD", "RAMSAY STREET"; "ramsay rd" completes "RAMSAY ROAD". Best narrowed by a suburb or postcode filter. "pi" in SYDNEY → "PIER STREET", "PITT STREET"
state State and territory abbreviations, from the abbreviation or the name. "new south" → "NSW"

Filter

A filter limits values to those held by addresses matching every field set.

{
    "filter":
    {
        "state":"{state abbreviation, e.g. NSW}",
        "locality":"{suburb}",
        "postcode":"{4-digit postcode}"
    }
}
Example

The streets of Sydney starting 'pi'.

Request

POST https://api.getaddress.io/typeahead/pi?api-key={your-api-key}

Request Body

{
    "search": ["street"],
    "filter":
    {
        "locality": "SYDNEY"
    }
}

Response

[
    "PIER STREET",
    "PITT STREET"
]

Options

Name Default Description Type
top 6 The number of values to return, 1–20. Also accepted as a query parameter on the GET. Number
search All fields The fields to complete. POST body only. Array
filter None Only values held by addresses in a state, suburb or postcode. POST body only. Object
same true false drops a lone value that only repeats the term, so a finished field stops offering itself back. POST body only. Boolean

Usage

  • Typeahead queries are rate limited but do not increase your usage.
  • A term is 1–50 characters. An unknown search field returns 400.

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.

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