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

Nearest Location

The Nearest Location API returns the places whose centres are nearest a latitude and longitude, nearest first, each with its distance in metres — which suburb a point is in, or near.

Request

GET https://api.getaddress.nz/nearest-location/{latitude}/{longitude}?api-key={your-api-key}
Example

The three places nearest 169 Lambton Quay, Wellington.

Request

GET https://api.getaddress.nz/nearest-location/-41.2828/174.7760?api-key={your-api-key}&top=3

Response (the shape; one suggestion per place, nearest first)

{
    "suggestions":
    [
        {
            "location": "{label, e.g. Wellington Central, Wellington 6011}",
            "url": "{/get-location/… for this place}",
            "id": "{location id, e.g. Wellington Central|Wellington|6011}",
            "distance": {metres}
        },
        …
    ]
}

Each suggestion resolves with the Get Location API like a Location suggestion does.

Options

Name Default Description Type
top 6 The number of places to return, 1–20. A query parameter. Number

Response Fields

Field Description
location / url / id As a Location suggestion.
distance Straight-line distance from the point to the place's centre, in whole metres.

Usage

  • A request that finds a place counts as 1 look-up against your plan's daily allowance.
  • A point with no New Zealand place within reach returns an empty list and costs nothing.
  • A latitude outside −90 to 90, or a longitude outside −180 to 180, returns 400.

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