Address Autocomplete API

The Address Autocomplete API is used to search the Addressfinder database to return closely matching addresses which can then be selected from by the user. This API works in tandem with the Address Metadata API which is used to load the metadata associated with the selected address.

Endpoint

New Zealand

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

Parameters

Parameter	Default	Description
`key`		Your unique licence key (find on Portal credentials) Required string
`secret`		Your unique secret key (find on Portal credentials). This is required when calling API endpoints without a referer. Optional string
`q`		The partial address being searched Optional string
`format`	`json`	The required format of the response. Optional string
`delivered`		This filter determines if the results are either delivered or not delivered by NZ Post: `0` A rarely used option that excludes addresses that NZ Post deliver to. `1` - Only returns addresses that are delivered to by NZ Post. Omit to not filter. Returns delivered and non-delivered addresses in the response. Optional string
`post_box`		This filter includes/excludes PO Box style addresses. `0` - Excludes PO Box type addresses from being returned in the response. `1` - Returns only PO Box, Private Bag, Community Mailbox and Counter Delivery address types. Omit to not filter. Returns PO Box type and standard addresses in the response. Optional string
`rural`		This filter includes/excludes rural/urban addresses: `0` - Excludes addresses likely to be considered rural by a courier company. `1` - A rarely used option that returns rural addresses only. Omit to not filter. Returns rural and urban addresses in the response Optional string
`strict`	`2`	Determines how closely matched the results should be to the `q` parameter: `0` - Normal search - Allows some address elements to be omitted but does not allow spelling errors. `1` - Strict search - Requires all address elements entered in `q` to be ordered and spelt correctly. `2` - Fuzzy search - Allows spelling errors and inaccurate address elements. Optional string
`region_code`		Only return addresses within the boundary of the selected region (Regional Authority): `1` - Only returns addresses from the Auckland Region `2` - Only returns addresses from the Bay of Plenty Region `3` - Only returns addresses from the Canterbury Region `4` - Only returns addresses from the Gisbourne Region `5` - Only returns addresses from the Hawke's Bay Region `6` - Only returns addresses from the Manawatu-Wanganui Region `7` - Only returns addresses from the Marlborough Region `8` - Only returns addresses from the Nelson Region `9` - Only returns addresses from the Northland Region `A` - Only returns addresses from the Otago Region `B` - Only returns addresses from the Southland Region `C` - Only returns addresses from the Taranaki Region `D` - Only returns addresses from the Tasman Region `E` - Only returns addresses from the Waikato Region `F` - Only returns addresses from the Wellington Region `G` - Only returns addresses from the West Coast Region `H` - Only returns addresses from the Chatham Islands Region Omit to not filter. Returns addresses from all Regions Optional string
`domain`		Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. Optional string
`max`	`10`	The maximum number of results to return. The default is 10 results. Optional integer
`highlight`		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: `1` - Highlighted. Omit to not return additional `highlighted_a` property Optional string
`ascii`		Set to `1` to reformat special characters like macrons and other accents characters with their ASCII equivalent (e.g. Pōneke and Café will be returned as Poneke and Cafe). Optional string

Responses

200 OK

Name	Type	Description	Example
`completions`	array	The API response will contain all the addresses and associated IDs (pxid) in the format requested in the API request.	-
`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.	184 Williams Street, Kaiapoi 7630
`success`	boolean	Indicates if the request was successful or not.	true

400 Bad request

Name	Type	Description	Example
`completions`	array	An empty array will be returned due to the error	-
`error_code`	string	A unique numerical value identifying the error that occured	1004
`message`	string	An informative message describing the error that occured	Secret not provided
`success`	boolean	Indicates if the request was successful or not	false

See API Error Reference for details.