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	Description	Test Value
`key`	Your unique licence key (find on Portal credentials) Type: `string` `required`
`secret`	Your unique secret key from Portal Credentials. You can also pass your secret key into the `Authorization` header of the request. Only required for server-to-server calls. Type: `string`
`q`	The partial address being searched Type: `string`
`format`	The required format of the response. Default value: `json` Type: `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. Type: `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. Type: `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 Type: `string`
`strict`	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. Default value: `2` Type: `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 Type: `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. Type: `string`
`max`	The maximum number of results to return. The default is 10 results. Default value: `10` Type: `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 Type: `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). Type: `string`

Responses

200 OK

Name	Description	Example
`completions`	The API response will contain all the addresses and associated IDs (pxid) in the format requested in the API request. Type: `array`	-
`a`	Canonical address as supplied by Land Information New Zealand or NZ Post. Type: `string`	184 Williams Street, Kaiapoi 7630
`pxid`	The unique address identifier. Type: `string`	2-.3.1q.2.4G.4c
`v`	This is a deprecated field and is only retained for backwards compatibility reasons. You should ignore this field. Type: `integer`	0
`highlighted_a`	When highlighting is enabled, contains the full address string with highlighted matching terms. Type: `string`	184 Williams Street, Kaiapoi 7630
`success`	Indicates if the request was successful or not. Type: `boolean`	true

400 Bad request

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

See API Error Reference for details.