Address Finder API


Use the NZ address finder API to validate and autocomplete addresses

Address Autocomplete

Addy offers a RESTful address finder API for address autocomplete applications. The API takes address fragments, validates it against the New Zealand Postal Address File (PAF) and Land Information New Zealand (LINZ) address datasets, and returns a collection of matched results.

Addy's address finder API uses techniques such as tokenisation, fuzzy matching and IP address prioritisation to ensure accurate address predictions are made even with common entry mistakes. This API is used by the JavaScript address finder and jQuery UI address finder widgets to provide predictive type-ahead address suggestions.

Vist the address finder page for a live address search demo.

FREE address finder API: It is 100% free to call this API to find NZ addresses. Sign up for free.

Address Finder API Endpoint


URL https://www.addy.co.nz/api/search/
HTTP Request Type GET

cURL Request

The example below will make a JSON request to search for "80 Queen" by adding the API key in the request header:

curl -X GET --header 'Accept: application/json' --header 'addy-api-key: demo-api-key' 'https://www.addy.co.nz/api/search?s=80+Queen'

Lookup "80 Queen" using the API key as a query string parameter:

curl -X GET --header 'Accept: application/json' 'https://www.addy.co.nz/api/search?key=demo-api-key&s=80+Queen'

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 finder API works in conjunction with the Address Details API.

Call the Address Details API endpoint (e.g. /api/address/2417575) to retrieve detailed address metadata for a search result.


Response Example: "80 Queen Street" search criteria

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

{
  "matched": 11,
  "addresses": [
    {
      "id": 2417575,
      "a": "80 Queen Street, Auckland Central, Auckland 1010"
    },
    {
      "id": 3828376,
      "a": "80 Queen Street, Masterton 5810"
    },
    {
      "id": 1220406,
      "a": "80 Queen Street, North Dunedin, Dunedin 9016"
    },
    {
      "id": 2398953,
      "a": "80 Queen Street, Northcote Point, Auckland 0627"
    },
    {
      "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"
    },
    {
      "id": 2405130,
      "a": "80/685 Queen Street East, Levin 5510"
    }
  ],
  "badwords": [],
  "q": null
}

Response Example: "Reception Desk 80 Queen Street" search criteria with JSONP callback method "done123"

  • https://www.addy.co.nz/api/search?key=demo-api-key&callback=done123&s=Reception Desk 80 Queen Street

done123({
  "matched": 11,
  "addresses": [
    {
      "id": 2417575,
      "a": "80 Queen Street, Auckland Central, Auckland 1010"
    },
    {
      "id": 3828376,
      "a": "80 Queen Street, Masterton 5810"
    },
    {
      "id": 1220406,
      "a": "80 Queen Street, North Dunedin, Dunedin 9016"
    },
    {
      "id": 2398953,
      "a": "80 Queen Street, Northcote Point, Auckland 0627"
    },
    {
      "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"
    },
    {
      "id": 2405130,
      "a": "80/685 Queen Street East, Levin 5510"
    }
  ],
  "badwords": [
    "reception",
    "desk"
  ],
  "q": "80 queen street"
})