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

Get

The Get API resolves an Autocomplete suggestion 'Id' to the full address.

Request

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

The API key goes in the api-key query parameter; a header is not accepted.

Example

Resolving the suggestion for '169 Lambton Quay, Wellington Central, Wellington 6011'.

Request

GET https://api.getaddress.nz/get/363752?api-key={your-api-key}

Response

The response is the address as LINZ publishes it, with an unofficial postcode added. Every string field is present on every address, and is empty when that address has no value for it. 

{
    "id": "363752",
    "address_id": "363752",
    "address_label": "169 Lambton Quay, Wellington Central, Wellington 6011",
    "address_status": "current",
    "flat_number": "",
    "number_first": "169",
    "number_last": "",
    "number_suffix": "",
    "full_road_name": "Lambton Quay",
    "locality_name": "Wellington Central",
    "town_city": "Wellington",
    "territorial_authority": "Wellington City",
    "postcode": "6011",
    "postcode_source": "road",
    "coordinates": {
        "latitude": -41.2828093667,
        "longitude": 174.7759540167
    }
}

Response Fields

Field Description
id / address_id LINZ's address_id, a number as text, e.g. "363752". Both carry the same value: the id you passed to Get.
address_label The one-line display label, the same text the suggestion showed.
address_status "current" when LINZ still publishes this address, "retired" when it has been withdrawn since. A retired address still resolves — an id you stored months ago keeps working — but it will never be suggested again.
flat_number The flat or unit, as LINZ writes it, e.g. "2", "7A" or "G04". Empty when the address has none.
number_first / number_last The street number, and the high end of a range (48-56 Queen Street). number_last is empty for a single number.
number_suffix The letter after the street number, e.g. "A" of 808A. Empty when none.
full_road_name The road's whole name, type included, e.g. "Lambton Quay".
locality_name The suburb or locality, e.g. "Wellington Central".
town_city The town or city, e.g. "Wellington".
territorial_authority The district or city council, e.g. "Wellington City" or "Selwyn District".
postcode The 4-digit postcode. Unofficial: it comes from the open_nz_postcodes project, not from NZ Post, and is wrong for roughly 5 addresses in 100. Empty when no postcode could be assigned. postcode_source says how far to trust it.
postcode_source How the postcode was assigned:
  • road — from the road the address is on.
  • suburb (single) — the suburb has one postcode.
  • suburb (majority) — most of the suburb's addresses have it. Lower confidence.
  • none — no postcode could be assigned; postcode is "".
  • corrected — set from customers' corrections to this address.
  • corrected (road) — set from customers' corrections that agree across the road.
coordinates The LINZ address point (WGS84), as latitude and longitude. Null when the address carries no coordinates.

A wrong postcode

If you or your user know first-hand that an address's postcode is wrong, report it with the Postcode correction API or from your console. Never copy postcodes from NZ Post's products or its postcode finder.

Usage

  • Each successful Get request counts as 1 look-up against your plan's daily allowance.

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