New Zealand Postcode Finder

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

Try it out

Why?

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.

Usage

Run free text searches like: http://postcodefinder.appspot.com/search?q=90+federal+st+auckland

The response is returned as application/json.

Response Fields

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

Errors Returned

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

Versioning

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.

Colophon

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

Questions, comments, feature requests should be directed to maetl@coretxt.net.nz.

Version 0.0.2. March 26th 2009.