addy

NZ
AU

addy

NZ
AU

Services

Pricing

Documentation

Contact

FAQ

Login

Address APIs

Address Finder API
Address Validation API
Address Details API
Address Discovery API
Postcode Finder API
Geocode Address API
Bounding Box API

Address Finder API Documentation

Use the NZ address finder API to validate and autocomplete addresses

Address Finder API Endpoint


URLhttps://api-nz.addysolutions.com/search/
HTTP Request TypeGET

cURL Request


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

1curl -X GET --header 'Accept: application/json' --header 'addy-api-key: demo-api-key' 'https://api-nz.addysolutions.com/search?s=80+Queen'
Remember to replace demo-api-key with your own API key.

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

1curl -X GET --header 'Accept: application/json' 'https://api-nz.addysolutions.com/search?key=demo-api-key&s=80+Queen'
Remember to replace demo-api-key with your own API key.

Request Parameters


ParameterDescriptionTypeRequiredExample
sSearch criteria / address fragment to query (minimum of 2 characters)stringYes85 Queen
maxNumber of addresses to return (default = 10, max = 50)integer (1 to 50)No20
exruralExclude rural addresses from the search results (default false)booleanNoTRUE
expostboxExclude Post Box addresses from the search results (default false)booleanNoTRUE
exundeliverExclude non-mail delivery addresses from the search results (default false)booleanNoTRUE
exspellingDisable spelling correction from address matching (default false)booleanNoFALSE
exwordDisable extra word removal from address matching (default false)booleanNoFALSE
exipDisable address sorting based on IP address proximity (default false)booleanNoFALSE
expostcode

Exclude addresses within certain postcodes, defined in a dash separated list of postcodes. See the complete list of postcodes

stringNo0622-1010-2112
inpostcode

Only include addresses within certain postcodes, defined in a dash separated list of postcodes. See the complete list of postcodes

stringNo0622-1010-2112
exregion

Exclude addresses within certain regions, defined in a dash separated list of region codes. See the complete list of region codes

stringNo1/2/03
inregion

Only include addresses within certain regions, defined in a dash separated list of region codes. See the complete list of region codes

stringNo1/2/03
exterritory

Exclude addresses within certain territories, defined in a dash separated list of territory codes. See the complete list of territory codes

stringNo5-6-7-8
interritory

Only include addresses within certain territories, defined in a dash separated list of territory codes. See the complete list of territory codes

stringNo5-6-7-8
callbackJSONP callback function namestringNocallback123

Response Properties


PropertyDescriptionTypeExample
addressesArray of address resultsaddress array[{address},{address}]
badwordsInvalid matching words that were removed from the search querystring arrayReception Desk
matchedTotal number of possible addresses that were matchesinteger559
qSearch criteria used after eliminating bad matching wordsstring array80 Queen

Address Properties

PropertyDescriptionTypeExample
aFull display name of the addressstring80 Queen Street, Auckland Central, Auckland 1010
idUnique identifier for the addressinteger2417575

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

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

Response Example:

"80 Queen Street" with no callback
https://api-nz.addysolutions.com/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://api-nz.addysolutions.com/search?key=demo-api-key&callback=done123&s=Reception Desk 80 Queen Street

typeof done123 === 'function' &&
  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"
  })

Sign up

Full support

Sign up

Full support

Address Services

Address AutocompleteAddress CleansingAddress GeocodingPostcode FinderPricingSign inSign up
© 2021 Addy LimitedTerms & Conditions
Made in Auckland, New Zealand
Looking for Addy Australia?