Validate

The Validate API confirms an address written on one line. It reads the unit, number, road, suburb, town and postcode however they are written, and answers with the one LINZ address the line describes — or says it cannot, rather than guess.

Request

GET POST https://api.getaddress.nz/validate/{address}?api-key={your-api-key}

URL-encode the address, but leave a unit's slash as it is: /validate/2/12%20East%20St%20… reads as unit 2, number 12.

Responses

Status	When	Body	Look-ups
200	Exactly one address fits the line.	The address, exactly as Get returns it.	1
300	Several addresses fit; or the line names no suburb or postcode to place it; or it names a building LINZ holds only as its units.	`candidates`: their ids, for Get. Up to 10. `primary_secondary`: `"PRIMARY"` when they are the units of the one building the line names (only the unit is missing); absent otherwise.	0
404	No address fits every word of the line.	A problem description.	0

Example: found

Request

GET https://api.getaddress.nz/validate/169 Lambton Quay, Wellington 6011?api-key={your-api-key}

Response (200 — every field Get returns; some shown)

{
    "id": "363752",
    "address_label": "169 Lambton Quay, Wellington Central, Wellington 6011",
    "address_status": "current",
    "number_first": "169",
    "full_road_name": "Lambton Quay",
    "locality_name": "Wellington Central",
    "town_city": "Wellington",
    "postcode": "6011",
    "postcode_source": "road",
    …
}

The postcode in the answer is unofficial: see postcode_source on Get.

Example: ambiguous

'12 Queen St' names no suburb or postcode, and there is a 12 Queen Street in several.

Response (300)

{
    "candidates": [
        "1131927",
        "1186326",
        …
    ]
}

Example: unit missing

'15 Trafalgar Street, Nelson 7010' is a building LINZ holds only as its flats, 1/15 to 8/15.

Response (300)

{
    "candidates": [
        "316159",
        "2004659",
        …
    ],
    "primary_secondary": "PRIMARY"
}

Ask for the flat number: 2/15 Trafalgar Street, Nelson 7010 is found.

How a line is read

A unit as 2/12, or as Unit 2, Flat 2, Apt 2, Shop 2 … The words are interchangeable: only the unit itself is checked.
Number ranges: 50 finds 48–56, and 48-56 must be that range. A letter is part of the number: 12A is not 12.
A level (Level 5) and a rural delivery number (RD 2) are read off and not checked: LINZ holds neither.
Road types written out or abbreviated (St, Rd, Tce …), and St as a saint (St Johns).
Macrons optional: Otahuhu finds Ōtāhuhu. The postcode, and New Zealand or NZ at the end, are optional.
One letter out in a word of five letters or more is forgiven: Lambtn finds Lambton.
Every other word must belong to the address. A word left over means a different address, and the answer is 404, not the nearest guess.

Usage

A found address (200) counts as 1 look-up against your plan's daily allowance.
Ambiguous (300) and not found (404) cost nothing, but count toward the rate limit.
An address is at most 200 characters.

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.