Address Autocomplete API (NZ)

Build
Send
Response
Errors

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 request URL

Use the form below to build your request URL from the parameters. A URL string will be generated from these parameters and sent to the API in order to provide insight into how the API works and the responses it returns.

Field Name	Value	Type	Description
key *		String	Your unique licence key (find on Portal overview page)
secret *		String	Your unique secret key (find on Portal overview page)
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` Manawatu-Wanganui `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`

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

Request URL

        
          /* 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.

Code	Error	Cause	Resolution
`1000`	Validation error	Returned when one of the supplied parameters is missing or incorrect. The response will contain a message attribute which explains the cause of the validation error. An example JSON response is shown below for a request which failed to include the `q` parameter. `{ completions: [ ], message: 'Q can not be blank', error_code: '1000' }`	Check that the supplied parameters contain valid values, and that the mandatory parameters have been included.
`1001`	Account key not found	Returned when the key included in your API call cannot be found in our database. This will normally happen when you make a copy ’n paste error.	Compare the key included in your API call with the key listed in the AddressFinder Portal overview page. Also confirm there are no additional spaces or characters in your API call.
`1002`	Account key is missing	Returned when you fail to send through your key with each request. The key is a mandatory parameter.	Check that you are using the correct parameter name `key`.
`1003`	Invalid domain	Returned when you embed AddressFinder on a website that differs from the domain that you specified in the AddressFinder Portal.	The AddressFinder Portal records the whitelist of allowed domains for your account. Login to the AddressFinder Portal and add the domain of this website to your account.
`1004`	Account secret missing	Returned when you fail to send through your secret with an API call. Can also occur when using the widget and the HTTP `Referer` header is not included.	Include the secret listed in the AddressFinder Portal overview page in your API call. When using the widget, you must load the page from a web server (e.g. localhost) and not a `file://` scheme.
`1005`	API calls require a Paid plan.	Returned if you try to call the API and you are on a Free plan. Free accounts are expected to use the JavaScript Widget only.	Consider upgrading to a Pro plan. Visit the AddressFinder Portal to change plan. A Developer plan is available for customers in development. Contact us to request the necessary plan change
`1006`	Invalid secret value	Returned when the supplied secret value does not match the value stored in our database. This will normally happen when you make a copy ’n paste error.	Compare the secret included in your API call with the secret listed in the AddressFinder Portal overview page. Also confirm there are no additional spaces or characters in your API call.
`1008`	Secret should not be supplied	This is a safety check to ensure that the secret parameter has not been included when making requests from your web browser. You should never include the secret on any web page.	The secret should be used for server-to-server API calls only.
`1009`	Account has been suspended	Returned when your account (Free plans only) has hit its 100% usage limit for the billing period.	Visit the AddressFinder Portal and upgrade your account to a Paid plan. Alternatively wait until the end of the month when suspended accounts are automatically reactivated.
`1011`	Record not found	Returned when the supplied address identifier cannot be found. This can happen when a stale identifier is included in the API call.	Do not save address identifiers in your database, as they are transisent and may change after each database update.
`1014`	Account Disabled	Your account has been disabled by AddressFinder support.	Contact AddressFinder support to reactivate your account.
`1015`	Cannot include domain parameter in a web request	You have included a domain parameter in your browser based API call.	Remove the domain parameter from your API call.
`1017`	This activity is not permitted on your current plan	You have attempted to use an AddressFinder service that is not valid for current plan.	Consider upgrading to a Pro plan. Visit the AddressFinder Portal to change plan. Alternatively Contact us to discuss plan options.
`1019`	HTTP Referer header record must be present when making a browser initiated API call	You have attempted to use the AddressFinder widget from a location that does not provide the referrer along with each query.	Host the widget on a website or browser.
`1020`	Your AddressFinder trial has ended	Returned when the trial term has ended.	Log into the AddressFinder Portal and upgrade your account to a suitable plan.
`1021`	Your AddressFinder trial has exceeded its allowed lookups.	Returned when you have exceeded the number of lookups permitted on the trial plan.	Log into the AddressFinder Portal and upgrade your account to a suitable plan.