Address Autocomplete API (NZ)

Build
Send
Response
Errors

This page contains the technical API information for our Address Autocomplete. Please visit our address autocomplete page if you are looking to learn more about the service

This API is used to power the autocomplete capability of the Addressfinder widget. It can also be used to power your own custom autocomplete functionality, such as in a mobile or desktop app. If you want to call this API from a web browser, there are some special guidelines that you will need to follow.

Build the GET request URL

Use the form below to build your request URL from the available parameters. The URL string will be generated and can be sent to the API in order to provide insight into how the API works and the response it returns. Or, if you are using Postman for your investigation, development and testing, include the desired parameters and copy and paste the request URL below into Postman's GET request URL field.

Field Name	Value	Type	Description
key *		String	Your unique licence key (find on Portal credentials)
secret *		String	Your unique secret key (find on Portal credentials). Alternatively, you can pass your secret key into the Authorization header of the request as such: `Authorization: your-secret`. FAQ: Learn more about authenticating direct API calls in request headers
q *		String	The partial address being searched.
format *		String	The required format of the response.
	Options json `json` for a response in json format. xml `xml` for a response in xml format.
delivered		String	This filter determines if the results are either delivered or not delivered by NZ Post.
	Options Non-delivered addresses only `0` A rarely used option that excludes addresses that NZ Post deliver to. Delivered addresses only `1`
post_box		String	This filter includes/excludes PO Box style addresses.
	Options Exclude PO Box addresses `0` PO Box only `1` Returns only PO Box, Private Bag, Community Mailbox and Counter Delivery address types.
rural		String	This filter includes/excludes rural/urban addresses.
	Options Urban addresses only `0` Excludes addresses likely to be considered rural by a courier company. Rural addresses only `1` A rarely used option that returns rural addresses only.
strict		String	Determines how closely matched the results should be to the `q` parameter.
	Options Normal search `0` Allows some address elements to be omitted but does not allow spelling errors. Strict search `1` Requires all address elements entered in `q` to be ordered and spelt correctly. Fuzzy search `2` Allows spelling errors and inaccurate address elements.
region_code		String	Only return addresses within the boundary of the selected region (Regional Authority).
	Options Auckland `1` Bay of Plenty `2` Canterbury `3` Gisborne `4` Hawke's Bay `5` Manawatū-Whanganui `6` Marlborough `7` Nelson `8` Northland `9` Otago `A` Southland `B` Taranaki `C` Tasman `D` Waikato `E` Wellington `F` West Coast `G` Chatham Islands `H`
domain		String	Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. FAQ: learn more about the domain parameter
max		Integer	The maximum number of results to return. A number between 1 and 100. The default is 10 results.
highlight		Integer	Returns an additional attribute in the response called `highlighted_a`. This attribute wraps the matching terms in the address with `<span class='af_hl'></span>` in order to highlight those terms.
	Options Highlighted `1`
ascii		Integer	A filter that replaces macron-containing characters with their ASCII counterparts. It doesn't exclude addresses with macron characters from the results, it translates these characters into their corresponding English equivalents within the addresses. Use when your systems are having issues processing macron-containing addresses.
	Options Converted `1` Converts the response to ASCII. Original Leaves the response as is, potentially containing macrons or non-ascii characters.

* Parameters marked with an asterisk are mandatory for this API call.

Request URL

https://api.addressfinder.io/api/nz/address/autocomplete/

      
        /* Click the button above to see a real API response here */
        {
          "success": true
        }

Response Specification

The API response will contain a hash with an element named completions, which is an array of hashes containing the following fields.

Field Name	Type	Description	Example
`a`	String	Canonical address as supplied by Land Information New Zealand or NZ Post.	184 Williams Street, Kaiapoi 7630
`pxid`	String	The unique address identifier.	2-.3.1q.2.4G.4c
`v`	Integer	This is a deprecated field and is only retained for backwards compatibility reasons. You should ignore this field.	0
`highlighted_a`	String	When highlighting is enabled, contains the full address string with highlighted matching terms.	<span class='af_hl'>184</span> <span class='af_hl'>Will</span>iams Street, Kaiapoi 7630
`success`	Boolean	Indicates if the request was successful or not.	true

Errors

Below are the possible errors that can be returned by the API.