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

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.

500 FREE postcode finder api call per month. Busy month? Choose a plan to meet your needs.

What is NZ postcode?

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


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

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:

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

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

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

Request Parameters


ParameterDescriptionTypeRequiredExample
sSearch criteria by postcode, suburb or city (minimum of 2 characters)stringYes85 Queen
maxNumber of postcode results to return (default = 10)integerNo10
callbackJSONP callback function namestringNocallback123

Response Properties


PropertyDescriptionTypeExample
postcodesArray of postcode modelspostcode model array[{postcode model},{postcode model}]

Postcode Model Description

PropertyDescriptionTypeExample
postcodeNZ Post code used for defining an areastring (max 4)1010
suburbSuburb namestring (max 60)Devonport
cityCity namestring (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://api-nz.addysolutions.com/postcode?key=demo-api-key&s=Devonport

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

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?