New Zealand Postcode Finder

A JSON API for extracting the postcode and location details from a valid New Zealand address.

Try it out


It's really useful to have programmatic access to postcodes - you can do interesting things with autocompletion or calculating a postcode for a given suburb or region without your users having to fill it in manually.

Actually, I made this for two reasons:

  1. New Zealand Post won't provide this data for free, and scraping the data off their site is against their terms and conditions (not to mention painful and messy, due to their insane URLs and obnoxious cookies and redirects). Even Google doesn't return NZ postcodes directly in their search API.
  2. I needed it for an app I was working on, and decided to expose it as a public service, rather than just encode it inside a single project.


Run free text searches like:

The response is returned as application/json.

Response Fields

4 digit New Zealand postcode
region new!
New Zealand region of the address
Latitude and longitude coordinates.
Full textual address of the location
Always NZ

Errors Returned

Either Unidentifiable location if the query cannot be mapped to an address, or Postcode not found if the address has no postcode.


This is a micro API, so there's not really too much point in versioning. If you want to use this in an app, and are unsure about potential impact of future changes, keep in mind the single contract that will be maintained for all future versions of the API: the response will always return a postcode field in the JSON object. Have no fear.

Future improvements include suburb/street based queries, and adding PO Box and Rural Delivery data.


Written in Python, running on Google App Engine, using the Google Search API.

Questions, comments, feature requests should be directed to

Version 0.0.2. March 26th 2009.