NZ

Documentation
REST API — New Zealand

NZ certified address validation API. Autocomplete and Metadata reference for the New Zealand interface tier.

Autocomplete - All

API Documentation

Introduction

The API provides the capability to custom-build your own auto-complete functionality for desktop, web, and mobile applications. Addresser Basic covers standard auto-complete functionality based on New Zealand Postal Address File.

Autocomplete All can be used only with Metadata - All variants to access relevant metadata of the address.

HTTP over SSL

GET 
https://api.addresser.com.au/getautocompletebasic-nz/all

Please note: All endpoints are accessible to registered users only. You can visit the Pricing section of our home page to select 7-days free "eCommerce" or "Business" plan to register for trial account.

Addresser - All - Autocomplete

Based on our predictive search, returns an array of partial/full match complete address for the given components of the user input address.

Example Usage: 

https://api.addresser.com.au/getautocompletebasic-nz/all?search_word=12&pdt=0

Request Headers

Field Type Description
x-api-key String

Your API key. You can access API Key after registering for either our 7-day free "Starter" or any other paid plans, via the "My Credentials" section after logging into the "My Addresser" portal.
You can visit the Pricing section of our home page to select 7-days free "Starter Plan" to register for trial account.

Parameter

Field Type Description
search_word String

Partial address searched for.
pdt optional Integer

Filter based on Post delivery types
"pdt=0" excludes PO Box type addresses.
"pdt=1" includes PO Box type addresses.

Response

200 Success Response Structure


      [
        {
            "FULL_ADDRESS": "12 SOMERVILLE ROAD RD 12 HAWERA 4672",
            "_id": "1ieAjocxxxxxxxxxxx",
           
        },
        {
            "FULL_ADDRESS": "12 DENBY HEIGHTS RD 12 HAWERA 4672",
            "_id": "UHMxxxxxxxxxxxx",
           
        }
      ]

API Errors

              {
                "errorCode": xxxx,
                "errorMessage": "xxx"
              }
Error Code Description Resolution
4073

Supplied Parameter is invalid

One of parameter is empty or has an invalid value.
4071

search_word is missing

Parameter search_word is missing.
4072

search_word cannot be empty

Input partial address into the search_word query string of the request URL.
4067

Postal Delivery Type (pdt) cannot be empty.

Input valid pdt type (0 or 1) to the pdt query string.
4068

Invalid Postal Delivery Type (pdt) name provided

pdt type can be either 0 or 1.
4076

API key is missing or invalid.

Check the API Key, you can get the correct API Key from the "Credentials" section of "My Addresser" portal.
4077

Invalid Method or API URL.

You have used an incorrect URL. Check the URL from the API documentation.
4080

You have exceeded the allowed quota.

You have reached the maximum limit of API calls on your current plan. You can choose to add an additional quota via the Pricing page of the Addresser website.
Below example error code and message. 
              {
                "errorCode": 4072,
                "errorMessage": "search_word cannot be empty."
              }

Response Specification

Field Type Description Example
FULL_ADDRESS String

Full address response the input partial address. The address data provided is based on the data source availability.

 FLAT 12 12 INGRAM STREET PAPAKURA 2110
_id String

Unique record identifier of the address

 1ieAjocxxxxxxxxxxx

Metadata - Certified

API Documentation

Introduction

The API provides capability to access the metadata of selected address from the Addresser NZ auto-complete API.

Metadata can be used only with Autocomplete variant to access relevant metadata of the address.

HTTP over SSL

https://api.addresser.com.au/getmetadatabasic-nz/all

Addresser - Metadata

Retrieves all metadata for selected Address from the Autocomplete address match results.

GET 
https://api.addresser.com.au/getmetadatabasic-nz/all

Example Usage

https://api.addresser.com.au/getmetadatabasic-nz/all?_id=42AuKokB5WPAYhJuepCs

Request Headers

Field Type Description
x-api-key String

Your API key. You can access API Key after registering for either our 7-days free "eCommerce" or "Business" plans, via the "My Crendentials" section after logging into the "My Addresser" portal.

You can visit the Pricing section of our home page to select 7-days free "Starter Plan" to register for trial account.

Parameter

Field Type Description
_id String

Record identifier from the Autocomplete search results.

Success Response

The success response from the API consists of single record of fields from the curated dataset consisting of Australia Post, GNAF and additional Local Government area-related information. Please note not all addresses have all three sets of information available.

                    [
                      {
                          "DELIVERY_POINT_ID": "422805",
                          "ADDRESS_TYPE": "URBAN",
                          "STREET_NUMBER": "12",
                          "STREET_ALPHA": null,
                          "UNIT_TYPE": "FLAT",
                          "UNIT_IDENTIFIER": "12",
                          "FLOOR": null,
                          "BUILDING_NAME": null,
                          "STREET_NAME": "INGRAM",
                          "STREET_TYPE": "STREET",
                          "STREET_DIRECTION": null,
                          "DELIVERY_SERVICE_TYPE": null,
                          "BOX_BAG_NUMBER": null,
                          "BOX_BAG_LOBBY_NAME": null,
                          "SUBURB_NAME": null,
                          "TOWN_CITY_MAILTOWN": "PAPAKURA",
                          "POSTCODE": "2110",
                          "RD_NUMBER": null,
                          "OLD_POSTCODE": "1703",
                          "FLOOR_LEVEL_TYPE": null,
                          "FLOOR_LEVEL_NBR": null,
                          "STREET_ALIASES_NAME": null,
                          "STREET_ALIASES_TYPE": null,
                          "STREET_ALIASES_DIRECTION": null,
                          "SUBURB_ALIASES_NAME": "ROSEHILL, PAPKURA, TAKANINI, RED HILL, HUNUA, ARDMORE, PAHUREHURE, OPAHEKE",
                          "TOWN_CITY_MAILTOWN_ALIASES_NAME": "AUCKLAND, PAPAKURA CITY, TAMAKI-MAKAU-RAU, SOUTH AUCKLAND",
                          "COUNTRY": "NZL",
                          "FULL_ADDRESS": "FLAT 12 12 INGRAM STREET PAPAKURA 2110",
                          "ADDRESS_LINE_1": "FLAT 12",
                          "ADDRESS_LINE_2": "12 INGRAM STREET",
                          "ADDRESS_LINE_3": "PAPAKURA 2110",
                          "ADDRESS_LINE_4": null,
                          "ADDRESS_LINE_5": null,
                          "DATA_SOURCE": "NZL_PAF"
                      }
                  ]

API Errors

                    {
                      "errorCode": xxxx,
                      "errorMessage": "xxx"
                    }
Error Code Description Resolution
4073

Supplied identifier is invalid.

Call support to helpdesk to resolve this issue.
4076

API key is missing or invalid.

Check the API Key, you can get the correct API Key from the "Credentials" section of "My Addresser" portal.
4077

Invalid Method or API URL.

You have used an incorrect URL. Check the URL from the API documentation.
4080

You have exceeded the allowed quota.

You have reached the maximum limit of API calls on your current plan. You can choose to add additional quota via Pricing page of the Addresser website.
Below example error code and message. 
                    {
                      "errorCode": 4072,
                      "errorMessage": "search_word cannot be empty."
                    }

Response Specification

Field Type Explanation Example
DELIVERY_POINT_ID

String

New Zealand Post Delivery point identifier of the address.

387497
ADDRESS_TYPE

String

Type of address as per NZ Post

URBAN
STREET_NUMBER

String

Street number

1283
STREET_ALPHA

String

Street number alpha value

A
(A to Z)
UNIT_TYPE

String

Describes the category of a sub-dwelling type within a building of building compiles. This is used in conjunction with the Unit Identifier address element.

FLAT
UNIT_IDENTIFIER

String

Holds the address elements that identify a specific deliver sub dwelling delivery point within a building or building complex

A combination of Characters and Numeric Values
E.g. BB2
FLOOR

String

Holds the Floor type and the identifier in a multi-level building

4
BUILDING_NAME

Integer

Holds the building property name for a recognized significant building

STREET_NAME

String

Holds the name of the street

2
STREET_TYPE

String

The street type that follows a Street Name to indicate the sub group the street has been allocated

STREET_DIRECTION

String

The direction of the thoroughfare split into sections that the delivery point is located on. It can indicate that the the thoroughfare is split from a point into sections that are north/south or east/west etc., or there is a central or extended section.

DELIVERY_SERVICE_TYPE

String

Describes the type of Delivery Service applicable to this delivery point

BOX_BAG_NUMBER

String

The PO Box/Private Bag number

BOX_BOX_LOBBY_NAME

String

The name of the New Zealand Post outlet or Agency outlet where the PO Box, Private Bag or Counter Delivery is physically located

SUBURB_NAME

String

Holds the name applied to a group of geographically associated streets

TOWN_CITY_MAILTOWN

String

Holds the name of the Town/ City/Mailtown associated with this delivery point.

PAPAKURA
POSTCODE

String

Holds the four digit code defined by New Zealand Post, which is used to describe the locations linked to sorting zones for mail sorting purposes

4345
RD_NUMBER

String

Rural Post – Rural Delivery route number

RD
OLD_POSTCODE

String

Holds the pre June 2006 four digit postcode for this delivery point

GNAF_NUMBER_LAST_SUFFIX

String

Street number last (for ranged addresses only) suffix, if any.

FLOOR_LEVEL_TYPE

String

Floor level type of the property if available.

FLOOR_LEVEL_NBR

Integer

Floor level number if available. Same as Floor.

STREET_ALIASES_NAME

String

Street name Alias if available.

George
STREET_ALIASES_TYPE

String

Street type alias if available

RD
STREET_ALIASES_DIRECTION

Integer

Street alias direction if alias street available

SUBURB_ALIASES_NAME

String

Alternate suburb name.

TOWN_CITY_MAILTOWN_ALIASES_NAME

String

Name of the Alternative Suburb Town/City/Mailtown.

COUNTRY

String

Three letter country code

FULL_ADDRESS

String

Single line full address.

ADDRESS_LINE_1

String

Combination of Unit type and number.

Please note address line values change based on the type of address. For a complete list of address lines you should refer to https://www.nzpost.co.nz/sites/nz/files/2021-10/adv356-address-and-layout-guide-aug-2021.pdf
ADDRESS_LINE_2

String

Street address

Please note address line values change based on the type of address. For a complete list of address lines you should refer to https://www.nzpost.co.nz/sites/nz/files/2021-10/adv356-address-and-layout-guide-aug-2021.pdf
ADDRESS_LINE_3

String

Suburb and Post code

Please note address line values change based on the type of address. For a complete list of address lines you should refer to https://www.nzpost.co.nz/sites/nz/files/2021-10/adv356-address-and-layout-guide-aug-2021.pdf
ADDRESS_LINE_4

String

Additional address line.

Please note address line values change based on the type of address. For a complete list of address lines you should refer to https://www.nzpost.co.nz/sites/nz/files/2021-10/adv356-address-and-layout-guide-aug-2021.pdf
ADDRESS_LINE_5

String

Additional address line.

Please note address line values change based on the type of address. For a complete list of address lines you should refer to https://www.nzpost.co.nz/sites/nz/files/2021-10/adv356-address-and-layout-guide-aug-2021.pdf
DATA_SOURCE

String

NZL_PAF

Please note address line values change based on the type of address. For a complete list of address lines you should refer to https://www.nzpost.co.nz/sites/nz/files/2021-10/adv356-address-and-layout-guide-aug-2021.pdf