Address Autocomplete API NZ


Search for New Zealand addresses and return the closest match.

Address Autocomplete API

Addy's Address Autocomplete API provides a fast and effective way to search over 2 million New Zealand addresses and return the closest matching address even when typos are made.

The Address Autocomplete API will return a list of addresses and unique Ids that can be used in conjunction with the Address Details API to retrieve metadata such as the city, suburb, postcode and geocodes of a selected address.

The API Tester and Swagger specification is available at https://api.addy.co.nz/.

Build a request URL

Use the form below to build an address autocomplete URL and issue a search query against the Address Autocomplete API.


Request URL Sample

Use the URL below to call and fetch addresses from the Address Autocomplete API.

https://api.addy.co.nz/search?key=demo-api-key&s=80 Queen Street

API Response

Response: "80 Queen Street" search criteria:

HTTP Status Code: 200 OK
{
  "matched": 208,
  "addresses": [
    {
      "id": 2417575,
      "a": "80 Queen Street, Auckland Central, Auckland 1010"
    },
    {
      "id": 2398953,
      "a": "80 Queen Street, Northcote Point, Auckland 0627"
    },
    {
      "id": 3828376,
      "a": "80 Queen Street, Masterton 5810"
    },
    {
      "id": 1220406,
      "a": "80 Queen Street, North Dunedin, Dunedin 9016"
    },
    {
      "id": 1541046,
      "a": "80 Queen Street, Richmond 7020"
    },
    {
      "id": 2261993,
      "a": "80 Queen Street, Te Kuiti 3910"
    },
    {
      "id": 4947299,
      "a": "80 Queen Street, Upper Hutt 5018"
    },
    {
      "id": 1907832,
      "a": "80 Queen Street, Waimate 7924"
    },
    {
      "id": 4350248,
      "a": "80 Queen Street, Waiuku 2123"
    },
    {
      "id": 2358361,
      "a": "80 Queen Street, Westport 7825"
    }
  ],
  "badwords": [],
  "q": null
}

Request Parameters


Parameter Description Type Required Example
s Search criteria / address fragment to query (minimum of 2 characters) string Yes 85 Queen
max Number of addresses to return (default = 10, max = 50) integer (1 to 50) No 20
exrural Exclude rural addresses from the search results (default false) boolean No True
expostbox Exclude Post Box addresses from the search results (default false) boolean No True
exundeliver Exclude non-mail delivery addresses from the search results (default false) boolean No True
exspelling Disable spelling correction from address matching (default false) boolean No False
exword Disable extra word removal from address matching (default false) boolean No False
exip Disable address sorting based on IP address proximity (default false) boolean No False
expostcode Exclude addresses with a postcode in the dash separated list of postcodes. See the complete list of postcodes filters string No 0622-1010-2112
inpostcode Only include addresses with a postcode in the dash separated list of postcodes. See the complete list of postcodes filters string No 0622-1010-2112
exregion Exclude addresses with a region in the dash separated list of region codes. See the complete list of region code filters string No 1-2-3
inregion Only include addresses with a region in the dash separated list of region codes. See the complete list of region code filters string No 1-2-3
exterritory Exclude addresses with a territory in the dash separated list of territory codes. See the complete list of territory code filters string No 5-6-7-8
interritory Only include addresses with a territory in the dash separated list of territory codes. See the complete list of territory code filters string No 5-6-7-8
callback JSONP callback function name string No callback123

Response Properties


Property Description Type Example
addresses Array of address results address array [{address},{address}]
badwords Invalid matching words that were removed from the search query string array Reception Desk
matched Total number of possible addresses that were matches integer 559
q Search criteria used after eliminating bad matching words string array 80 Queen

Address Response Property Description

Property Description Type Example
a Full display name of the address string 80 Queen Street, Auckland Central, Auckland 1010
id Unique identifier for the address integer 2417575

Addy's Address Autocomplete API works in conjunction with the Address Details API.

Call the Address Details API endpoint (e.g. https://api.addy.co.nz/address/2417575?key=demo-api-key) to retrieve detailed address metadata for a search result.

Response Codes

The following HTTP status codes are returned by the API:

Code Type Description
200 OK The request was successful. A valid JSON, JSONP or XML response will be returned.
400 Bad Request The request is invalid (e.g. invalid parameters).
401 Unauthorized The API Key is invalid or missing.
500 Internal Server Error An unexpected condition was encountered.