Location

The Location API suggests places for a partly typed suburb or postcode. A place is one suburb, state and postcode, as G-NAF names them — a suburb that spans two postcodes is two places.

Request

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

Response, for 'northb'

{
    "suggestions":
    [
        {
            "location": "NORTHBRIDGE NSW 2063",
            "url": "/get-location/northbridge-nsw-2063",
            "id": "northbridge-nsw-2063"
        },
        {
            "location": "NORTHBRIDGE WA 6003",
            "url": "/get-location/northbridge-wa-6003",
            "id": "northbridge-wa-6003"
        }
    ]
}

A term matches the start of any word of the place, so 'bon' finds BONDI and NORTH BONDI, and a postcode works as well as a name. Among equally good matches, the place with more addresses comes first.

The selected 'Id' is passed to the 'Get Location' API to return the place and its centre.

Request

GET https://api.getaddress.io/get-location/{id}?api-key={your-api-key}  

A place's id is built from its suburb, state and postcode, so it is the same in every G-NAF release — it is safe to store.

Authentication

Your API key goes in the api-key query parameter, as above. It is the only place the key is read from.

Filter

A filter limits results to specific criteria. Send it as the body of a POST to the same URL.

Request

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

Filtering 'state' to 'WA' will only return places in Western Australia.

{
    "filter":
    {
        "state":"WA"
    }
}

Location

Prefers places closer to a point. Nothing is excluded: places near the point come first, and the rest of the list is filled from everywhere. A request made with a domain token prefers places near the visitor automatically; on a server, pass your end user's ip_address for the same effect.

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

With that location, 'northb' returns NORTHBRIDGE WA 6003 before NORTHBRIDGE NSW 2063.

Options

Domain Tokens