Location Autocomplete API

This API lets you search for streets, suburbs, cities, and/or regions — collectively called "locations". The filters (like street, suburb, city, region) are applied additively. To return multiple location types, exclude the location types you don’t want. Example: To search for suburbs and cities only, set street=0 and region=0. This API works in tandem with the Location Metadata API.

Endpoint

New Zealand

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

Parameters

Parameter	Default	Description	Test Value
key		Your unique Addressfinder license key (find on Portal credentials). Required string
secret		Your unique secret key. You can also pass your secret key into the Authorization header of the request. Only required for server-to-server calls. Optional string
q		The query string to be matched with the location. Required string
format	json	The format of the response. Required string	-- Select --jsonxml
street		Set to 0 to exclude streets, 1 to include only streets. Optional string	-- Select --01
suburb		Set to 0 to exclude suburbs, 1 to include only suburbs. Optional string	-- Select --01
city		Set to 0 to exclude cities, 1 to include only cities. Optional string	-- Select --01
region		Set to 0 to exclude regions, 1 to include only regions. Optional string	-- Select --01
region_code		Restricts results to a region. Valid codes include: 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. Optional string
strict	0	Match strictness: - 0: normal (no spelling errors) - 1: strict (must be ordered and spelled correctly) - 2: fuzzy (allows misspelling) Optional string	-- Select --012
domain		Used to identify the calling service in the Addressfinder Portal. Must be a registered domain. Optional string
max	10	Max results to return (1–100). Optional integer
highlight		Set to 1 to return an attribute highlighted_a which wraps matched text with <span class='af_hl'></span>. Optional integer	-- Select --01

Responses

200 A list of location autocomplete completions

Name	Type	Description	Example
completions	array		-
a	string	Canonical location as supplied by data sources.	Willcox Grove, Naenae, Lower Hutt
pxid	string	Unique identifier for the location.	1-.F.b.M.1C
success	boolean	True if the request completed successfully.	true

400 Invalid input or missing required parameters.

Name	Type	Description	Example
error	string		Missing required parameter 'key'

See API Error Reference for details.