Address Discovery API


Use the Address Discovery API to retrieve bulk addresses using optional filters

Overview

The Address Discovery API is great at finding and retrieving bulk New Zealand addresses based on optional filter criteria. For example, retrieve all addresses by road, suburb, city, postcode, territory or region.

Use cases for this API:

Refreshing Addresses: Retrieve addresses that were modified after a given date to keep your database up to date and improve your address statement of accuracy.

Combining Census Data: Find all of the properties in meshblock (a small geographic location as defined by Statistics NZ), to get insight into census data such as average income, age, population, religion, gender diversity and more.

FREE Address Discovery API: It is 100% free to call this API and retrieve bulk NZ addresses. Sign up for free.

API Endpoint


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

cURL Request

The example below will make a JSON request to retrieve all of the addresses with a postcode of 1010:

curl -X GET --header 'Accept: application/json' 'https://www.addy.co.nz/api/discovery?key=demo-api-key&postcode=1010'

Request Parameters


Parameter Description Type Example
limit Number of addresses to return per batch (default = 100, maximum = 1000) integer 200
offset Offset to continue the paging (default = 0) integer 5
parcelid Filter by Land Information New Zealand (LINZ) Parcel Identifier integer 2027703
meshblock Filter by Meshblock as defined by Statistics NZ (2013 Census dataset) integer 438102
streetnumber Filter by street number string 11
road Filter by road name (full road name required) string Queen Street
suburb Filter by suburb name (full suburb name required) string Takapuna
mailtown Filter by mail town name (full mailtown name required) string Hamilton
city Filter by city name (full city name required) string Hamilton
territory Filter by territory name (full territory name required) string Hamilton City
region Filter by region name (full region name required excl. "Region" suffix) string Waikato
postcode Filter by 4 digit postcode string 0622
paf Include/exclude NZ Post addresses only. (True = NZ Post Only) boolean true
modifiedbydate Date since the address was last modified date 2018-01-22

Response Properties


Property Description Type Example
addresses Array of address results address array [{address},{address}]
_links Links for paging through the results URI /api/discovery?offset=100&limit=500

Address Response Property Description

Property Description Type Example
id Unique identifier for the address integer 2417575
displayname Full display name of the address string 80 Queen Street, Auckland Central, Auckland 1010
_link Link to Details API for retrieving metadata string /api/address/2417575

The Address Discovery 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 for retrieving the first 2 addresses from "Lomond Street"

https://www.addy.co.nz/api/discovery/key=demo-api-key&limit=2&road=Lomond+treet

{
  "addresses": [
    {
      "id": 1199201,
      "displayname": "1 Lomond Street, Caversham, Dunedin 9012",
      "_link": "/api/address/1199201"
    },
    {
      "id": 1199202,
      "displayname": "3 Lomond Street, Caversham, Dunedin 9012",
      "_link": "/api/address/1199202"
    }
  ],
  "_links": {
    "next": "/api/discovery?limit=2&road=Lomond+Street&offset=2"
  }
}