Australia Post provides several APIs for developers to use. You can find the developer centre website here. In this post, I'm going to introduce how to use Postage Assessment Calculator and Postcode Search.

Basically, postcode search is a part of postage calculation service. You are expected to search only as deep as suburb level. You can't search street names with this. Let's start with registration.

Registration

In order to use this API, you must have an Auspost account. If you don't have one, you can signup here 1 to create a new account. Once an account is created, the API key can be obtained at here 2.

As you can see the screenshot above, in order to request the API key, you must use the same email address as the one used for the Auspost account. Once you submit your request, you will receive a confirmation email from Auspost.

Make sure that your API key is as long as 36 characters including 4 hyphens.

API Consumption

Now, you have received your API key to consume the postcode search API. In case your API key doesn't work, don't worry. You can send a request through Twitter, Facebook or Website. They will soon sort out the API authentication issue.

Now, try how the API works through Fiddler. The API is a RESTful web service. So, we can simply send an HTTP request to the API server and get a response with either JSON or XML format. You can find the technical specification here 3.

Within the technical specification document, there are actually two API servers, one for production (https://auspost.com.au) and the other for test (https://test.npe.auspost.com.au). However, your API key might not be working at the test server. Therefore, just use the production service.

NOTE: You might be asked to install Fiddler root certificate as Fiddler needs to decrypt HTTPS requests and responses.

AUTH-KEY: [YOUR API key of 36 characters length, including hyphens]

Request URL: https://auspost.com.au/api/postcode/search.json?q=3000&state=VIC

Put your API key into the header and set the postcode search URL like above. Make sure that your API key must contain hyphens, which is opposed to the technical specification. The document actually states the API key is 32 characters length which omits hyphens. However, this is not correct. THE HYPHENS MUST BE INCLUDED. The following screenshots are actual request and response.

As you can see above, the JSON response was returned.

So far, we have briefly looked into the postcode search API provided by Australia Post. It's very convenient for developers to search postcode without storing postcode data locally. Of course, as Australia Post provides the full postcode data regularly, we can download it from the website, store it into our database and use it.