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	Description	Test Value
key	Your unique Addressfinder license 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 query string to be matched with the location. Type: string required
format	The format of the response. Default value: json Type: string required	-- Select --jsonxml
street	Set to 0 to exclude streets, 1 to include only streets. Type: string	-- Select --01
suburb	Set to 0 to exclude suburbs, 1 to include only suburbs. Type: string	-- Select --01
city	Set to 0 to exclude cities, 1 to include only cities. Type: string	-- Select --01
region	Set to 0 to exclude regions, 1 to include only regions. Type: 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. Type: string
strict	Match strictness: - 0: normal (no spelling errors) - 1: strict (must be ordered and spelled correctly) - 2: fuzzy (allows misspelling) Default value: 0 Type: string	-- Select --012
domain	Used to identify the calling service in the Addressfinder Portal. Must be a registered domain. Type: string
max	Max results to return (1–100). Default value: 10 Type: integer
highlight	Set to 1 to return an attribute highlighted_a which wraps matched text with <span class='af_hl'></span>. Type: integer	-- Select --01

Responses

200 A list of location autocomplete completions

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

400 Invalid input or missing required parameters.

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

See API Error Reference for details.