Address Validation API


Use the NZ address validation API to clean, standardise and format addresses

Quality Address Data

Addy's address validation API, also know as the address cleansing API or address correction API, will verify, cleanse, standardise and format addresses to deliver complete, accurate and enhanced data. Use Addy's address finder API for real-time address validation and autocomplete to prevent address mistakes at the point of entry.

This page is intended for API developers that would like to integrate with Addy's address matching API. Visit the address cleansing page to validate your bulk list of customer addresses using an Excel spreadsheet.

1,500 FREE Address Validation API requests per month. Sign up to get started.

Quality Address Data

Given partial addresses with missing suburbs, cities or postcodes, the single, easy to integrate address validation API will standardise and complete your addresses. Addresses are formatted according to NZ Post standards to provide better consistency and enable your business to apply for bulk mail discounts due to a higher statement of accuracy (SOA).


Enhanced Address Data

Detailed information such as region, territory, geocoding and meshblock data is included in each validated address to enhance the benefits of your existing address database. This will enable new capabilities and service offerings, such as better target marketing or provide valuable insights about your customers.

Easily visualise customer addresses by plotting them on a map, using business intelligence tools such as Tableau or Microsoft Power BI Desktop (free). Join your addresses with the Stats NZ Census data (2013, 2018) to get insights on customer demographics such as households, income, age, education and more.


Accurate Address Data

Addy's cleansing engine will indicate the validity of each address when potential duplicates are encountered, and provide alternative address recommendations that can be validated easily.

For example, the incomplete address "80 Queen Street Auckland" has two possible, equally valid matches:

  • 80 Queen Street, Auckland Central, Auckland 1010
  • 80 Queen Street, Northcote Point, Auckland 0627

Addy provides the ability to choose which address is correct. You can also use a strategy to email customers with unmatched addresses to validate that their address is accurate and allow them to correct it. Read our blog about address cleansing strategies.


Configurable Matching

Addy's address validation API is accurate and highly configurable to meet your unique business requirements. By simply changing a couple of parameters, you can enable or disable features such as fuzzy matching, spelling correction and invalid word removal (people names, business names, legal descriptions).

Address Validation API Endpoint


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

cURL Request

The example below will make a JSON request to validate for "80 Queeen St Aucland Centril" 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/validate?address=80 Queeen St Aucland Centril'

Validate "80 Queeen St Aucland Centril" using the API key as a query string parameter:

curl -X GET --header 'Accept: application/json' 'https://www.addy.co.nz/api/validate?key=demo-api-key&address=80 Queeen St Aucland Centril'

Request Parameters


Parameter Description Type Required Example
address An address to validate, cleanse and format string Yes 80 Queen Street, Auckland
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
callback JSONP callback function name string No callback123

Response Properties


Property Description Type Example
address Validated address address details See Address Details API
alternatives Array of alternative address matches address array [{address},{address}]
reason Notification message when the address could not be matched or when multiple addresses are returned that requires manual validation string No matches found

Response Example: "80 Queeen St Aucland Centril" validation criteria

  • https://www.addy.co.nz/api/search?key=demo-api-key&address=80 Queeen St Aucland Centril

{
  "address": {
    "id": 2417575,
    "dpid": 1540203,
    "linzid": 2027703,
    "parcelid": 6917300,
    "meshblock": 438102,
    "number": "80",
    "numberfull": "80",
    "numberdisplay": "80",
    "rdnumber": "",
    "alpha": "",
    "unittype": "",
    "unitnumber": "",
    "floor": "",
    "street": "Queen Street",
    "suburb": "Auckland Central",
    "city": "Auckland",
    "mailtown": "Auckland",
    "territory": "Auckland",
    "region": "Auckland",
    "postcode": "1010",
    "building": "",
    "full": "80 Queen Street, Auckland Central, Auckland 1010",
    "displayline": "80 Queen Street",
    "address1": "80 Queen Street",
    "address2": "Auckland Central",
    "address3": "Auckland 1010",
    "address4": "",
    "type": "Urban",
    "boxbagnumber": "",
    "boxbaglobby": "",
    "x": "174.766376",
    "y": "-36.846225",
    "modified": "2018-01-22",
    "paf": true,
    "deleted": false
  },
  "alternatives": [],
  "reason": null
}

Response Example: "80 Queen Street Auckland" validation criteria with multiple valid matches

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

{
  "address": {
    "id": 2417575,
    "dpid": 1540203,
    "linzid": 2027703,
    "parcelid": 6917300,
    "meshblock": 438102,
    "number": "80",
    "numberfull": "80",
    "numberdisplay": "80",
    "rdnumber": "",
    "alpha": "",
    "unittype": "",
    "unitnumber": "",
    "floor": "",
    "street": "Queen Street",
    "suburb": "Auckland Central",
    "city": "Auckland",
    "mailtown": "Auckland",
    "territory": "Auckland",
    "region": "Auckland",
    "postcode": "1010",
    "building": "",
    "full": "80 Queen Street, Auckland Central, Auckland 1010",
    "displayline": "80 Queen Street",
    "address1": "80 Queen Street",
    "address2": "Auckland Central",
    "address3": "Auckland 1010",
    "address4": "",
    "type": "Urban",
    "boxbagnumber": "",
    "boxbaglobby": "",
    "x": "174.766376",
    "y": "-36.846225",
    "modified": "2018-01-22",
    "paf": true,
    "deleted": false
  },
  "alternatives": [
    {
      "id": 2398953,
      "a": "80 Queen Street, Northcote Point, Auckland 0627"
    }
  ],
  "reason": "Review alternative addresses."
}