Autocomplete

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

Request

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

Response

For the term '12 queen st' (two of the suggestions shown).

{
    "suggestions":
    [
        {
            "address": "12 Queen Street, Auckland Central, Auckland 1010",
            "url": "/get/1131927",
            "id": "1131927"
        },
        {
            "address": "12 Queen Street, Ōtāhuhu, Auckland 1062",
            "url": "/get/1186326",
            "id": "1186326"
        },
        …
    ]
}

Macrons are optional when typing: 'otahuhu' finds Ōtāhuhu. The postcode on the end of a suggestion is unofficial — see Get and its postcode_source.

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

Request

GET https://api.getaddress.nz/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":
    {
        "town_city":"{town or city, e.g. Auckland}",
        "locality":"{suburb / locality}",
        "postcode":"{4-digit postcode}",
        "radius":{
            "km":"{max distance from lat/long in kilometres}",
            "longitude":{longitude},
            "latitude":{latitude}
        }
    }
}

Filtering 'town_city' to 'Auckland' will only return addresses in Auckland

Request

{
    "filter":
    {
        "town_city":"Auckland"
    }
}

Location

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

Request

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

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 New Zealand: '12 Queen St' is a real address in Auckland Central and in Ōtāhuhu, among others, and without a location they all 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 town_city, 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 New Zealand, 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

Domain Tokens

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