NZ Postcode Finder API


Use the Postcode Finder API to find and autocomplete post codes

Overview

Addy's RESTful Postcode Finder API, also know as the Postcode Search API or Postcode Lookup API, will find all of the postal codes in New Zealand and provide the capability to filter post codes by suburb or city. The post code finder takes postcode, city or suburb fragments and validates them it against the New Zealand Postal Address File (PAF) for accurate search results.

FREE Postcode Finder API: It is 100% free to call this API to retrieve NZ postcodes. Sign up for free.

What is a NZ post code?

New Zealand uses a unique 4-digit postcode, defined by NZ Post to help identify the region, city and suburb used for mail deliveries.

Why are postcodes important?

Using a service such as a NZ post code finder will validate that an accurate postcode was entered to reduce delays caused by returned mail or multiple re-deliveries.

What is fuzzy post code searching?

Fuzzy postcode searching is used for returning accurate post codes even when city or suburb filters are entered with spelling mistakes and typos.

API Endpoint


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

cURL Request

The example below will make a JSON request to search for post codes in "Devonport" 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/postcode?s=Devonport'

Lookup the "Devonport" postcodes using the API key as a query string parameter:

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

Request Parameters


Parameter Description Type Required Example
s Search criteria by postcode, suburb or city (minimum of 2 characters) string Yes 85 Queen
max Number of postcode results to return (default = 10) integer No 10
callback JSONP callback function name string No callback123

Response Properties


Property Description Type Example
postcodes Array of postcode models postcode model array [{postcode model},{postcode model}]

Postcode Model Description

Property Description Type Example
postcode NZ Post code used for defining an area string (max 4) 1010
suburb Suburb name string (max 60) Devonport
city City name string (max 60) Auckland

Call the Address Discovery API to retrieve all of the addresses by postcode, city or suburb.


Response Example: "Devonport" suburb search criteria

  • https://www.addy.co.nz/api/postcode?key=demo-api-key&s=Devonport

{
  "postcodes": [
    {
      "postcode": "0624",
      "city": "Auckland",
      "suburb": "Devonport"
    },
    {
      "postcode": "0622",
      "city": "Auckland",
      "suburb": "Devonport"
    }
  ]
}