Address Details API


Use the Address Details API to retrieve address metadata by ID, DPID or LINZ ID

Overview

Given an unique address identifier, such as Addy's Address ID, NZ Post's Delivery Point Identifier (DPID) or LINZ's Street Address ID, the Address Details API will return a list of properties / metadata about that address.

Vist the address validation page for a live address search demo that returns all address metadata.

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

API Endpoint


URL Description
https://www.addy.co.nz/api/address/{id} Retrieve an address using Addy's Address ID (e.g. the "id" property from the address finder API).
https://www.addy.co.nz/api/address?type=addyid&id={id} Retrieve an address using Addy's Address ID (e.g. the "id" property from the address finder API).
https://www.addy.co.nz/api/address?type=dpid&id={id} Retrieve an address using NZ Post's Delivery Point Identifier (DPID).
https://www.addy.co.nz/api/address?type=linzid&id={id} Retrieve an address using LINZ's Street Address ID (street_id).

cURL Request

The example below will make a JSON request to retrieve the address ID 2417575 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/address/2417575'

Lookup address "2417575" using the API key as a query string parameter:

curl -X GET --header 'Accept: application/json' 'https://www.addy.co.nz/api/address/2417575?key=demo-api-key'

Request Parameters


Request by Path

Parameter Description Type Required Example
{id} Address Identifier (see the "id" field in the address finder API response) path Yes https://www.addy.co.nz/api/address/2417575

Request Parameters by Type

Parameter Description Type Required Example
{type} The type of identifier (addyid, dpid or linzid) querystring Yes https://www.addy.co.nz/api/address?type=dpid&id=1540203
{id} Address Identifier based on the type parameter querystring Yes https://www.addy.co.nz/api/address?type=dpid&id=1540203

Address Metadata


Property Description Type Example
id Unique Addy identifier integer 2417575
dpid Unique NZ Post identifier. This property can be null for a non-mail deliverable address integer 1540203
linzid Unique Land Information New Zealand (LINZ) identifier integer 2027703
meshblock Unique Statistics New Zealand (Stats NZ) identifier to match census data integer 438102
number Street number. Street number will be "80" in case of "80A Queen Street" integer 80
rdnubmer Rural delivery number (postal only) for rural addresses string (max 10) 33
alpha Street alpha e.g. "A" in the case of "80A Queen Street" string (max 20) A
unittype Type of unit e.g. "FLAT" in "FLAT 3, 80 Queen Street" string (max 20) FLAT
unitnumber Unit number e.g. "3" in "FLAT 3, 80 Queen Street" string (max 20) 3
floor Floor number e.g. "Floor 5" in "Floor 5, 80 Queen Street" string (max 20) Floor 5
street Street name. The name of the street / road, including prefix string (max 60) Queen Street
suburb Suburb name string (max 60) Auckland Central
city Name of the town or city provided by Land Information New Zealand (LINZ) string (max 60) Auckland
mailtown Name of the town or city provided by NZ Post string (max 60) Auckland
territory Territorial authority of the address. See districts of NZ string (max 20) Auckland
region Regional authority of the address. See regions of NZ string (max 20) Auckland
postcode NZ Post code used for defining an area string (max 4) 1010
building Name of the building string (max 60) Deloitte Centre
full Full display name or label for an address string (max 90) 80 Queen Street, Auckland Central, Auckland 1010
displayline One line address display name string (max 70) 80 Queen Street
address1 Line 1 in a 4 address field form string (max 60) Suite 8, Floor 3
address2 Line 2 in a 4 address field form string (max 60) 80 Queen Street
address3 Line 3 in a 4 address field form string (max 60) Auckland Central
address4 Line 4 in a 4 address field form string (max 60) Auckland 1010
type Address Type (Urban, Rural, PostBox, NonPostal) string (max 9) URBAN
boxbagnumber The PO Box number for PO Box addresses integer 100
boxbaglobby NZ Post outlet or agency where the PO Box is located string (max 60) Auckland
x Longitude coordinates in WGS84 format string (max 20) 174.766357421875
y Latitude coordinates in WGS84 format string (max 20) -36.84621047973633
modified Last updated date date 2018-01-22
paf True/False to indicate if the address was sourced from PAF (or LINZ = false) boolean true
deleted True/False to indicate if the address was deleted from the source (PAF or LINZ) boolean false

Response Example for id 2417575

https://www.addy.co.nz/api/address/2417575?key=demo-api-key

{
  "id": 2417575,
  "dpid": 1540203,
  "linzid": 2027703,
  "parcelid": 6917300,
  "meshblock": 438102,
  "number": "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.766357421875",
  "y": "-36.84621047973633",
  "modified": "2018-01-22",
  "paf": true,
  "deleted": false
}

Response Example for id 2417575 with JSONP callback method "done345"

https://www.addy.co.nz/api/address/2417575?key=demo-api-key&callback=done345

done345({
  "id": 2417575,
  "dpid": 1540203,
  "linzid": 2027703,
  "parcelid": 6917300,
  "meshblock": 438102,
  "number": "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.766357421875",
  "y": "-36.84621047973633",
  "modified": "2018-01-22",
  "paf": true,
  "deleted": false
})