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 street, suburb, town or city, or postcode. It returns plain values, not addresses. Macrons are optional: 'hawera' completes Hāwera.

Request

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

Request

GET https://api.getaddress.nz/typeahead/hawer?api-key={your-api-key}

Response (first value shown)

[
    "Hāwera",
    …
]

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

Search

Restricts the search to specific fields. Send it as the body of a POST. There is no state field: New Zealand has none.

All possible search fields:

{
    "search": ["street", "locality", "town_city", "postcode"]
}
Field Completes Example
street Road names as LINZ writes them, type and all. A road in several suburbs is one value. Any word can be typed first. "lambton" → "Lambton Quay"
locality Suburbs and localities, as LINZ names them. A name held in two towns is one value. "wellington c" → "Wellington Central"
town_city Towns and cities, as LINZ names them. "rollest" → "Rolleston"
postcode Four-digit unofficial postcodes, from the digits typed. "601" → "6011", …

Filter

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

{
    "filter":
    {
        "town_city":"{town or city, e.g. Hāwera}",
        "locality":"{suburb}",
        "postcode":"{4-digit postcode}"
    }
}
Example

The suburbs of Hāwera starting 'norm'.

Request

POST https://api.getaddress.nz/typeahead/norm?api-key={your-api-key}

Request Body

{
    "search": ["locality"],
    "filter":
    {
        "town_city": "Hāwera"
    }
}

Response

[
    "Normanby"
]

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 places in a town or city, 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, /nearest, /distance, /location, /get-location, /nearest-location, /typeahead and reporting a wrong postcode with POST /postcode-correction. 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