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 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.

500 FREE completed address fields per month. Busy month? Choose a plan to meet your needs.

API Endpoint


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

cURL Request


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

1curl -X GET --header 'Accept: application/json' 'https://api-nz.addysolutions.com/discovery?key=demo-api-key&postcode=1010'
Remember to replace demo-api-key with your own API key.

Request Parameters


ParameterDescriptionTypeExample
limitNumber of addresses to return per batch (default = 100, maximum = 1000)integer200
offsetOffset to continue the paging (default = 0)integer5
parcelidFilter by Land Information New Zealand (LINZ) Parcel Identifierinteger2027703
meshblockFilter by Meshblock as defined by Statistics NZ (2013 Census dataset)integer438102
streetnumberFilter by street number11
roadFilter by road name (full road name required)stringQueen Street
suburbFilter by suburb name (full suburb name required)stringTakapuna
mailtownFilter by mail town name (full mailtown name required)stringHamilton
cityFilter by city name (full city name required)stringHamilton
territoryFilter by territory name (full territory name required)stringHamilton City
regionFilter by region name (full region name required excl. "Region" suffix)stringWaikato
postcodeFilter by 4 digit postcodestring0622
pafInclude/exclude NZ Post addresses only. (True = NZ Post Only)booleantrue
modifiedbydateDate since the address was last modifieddate2018-01-22

Response Properties


PropertyDescriptionTypeExample
addressArray of address resultsaddress array[{address},{address}]
_linksLinks for paging through the resultsURI/discovery?offset=100&limit=500

Address Response Property Description

PropertyDescriptionTypeExample
idUnique identifier for the addressinteger2417575
displaynameFull display name of the addressstring80 Queen Street, Auckland Central, Auckland 1010
_linkLink to Details API for retrieving metadatastring/address/2417575

The Address Discovery API works in conjunction with the Address Details API.

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

Response Example for retrieving the first 2 addresses from "Lomond Street"

https://api-nz.addysolutions.com/discovery/key=demo-api-key&limit=2&road=Lomond+treet
{
    "addresses": [
      {
        "id": 1199201,
        "displayname": "1 Lomond Street, Caversham, Dunedin 9012",
        "_link": "/address/1199201"
      },
      {
        "id": 1199202,
        "displayname": "3 Lomond Street, Caversham, Dunedin 9012",
        "_link": "/address/1199202"
      }
    ],
    "_links": {
      "next": "/discovery?limit=2&road=Lomond+Street&offset=2"
    }
  }

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?