Australia Postcode XML API

and like us on FB

Not unlike the Postcodez API that permits a user to extract USA zipcode details, this post will show you how to use the ePostcodes.com.au API to search details relating to Australian postal codes. Note: This API is depreciated. Instead, use our JSON API.

The ePostcodes website was initially a placeholder for another site that we never got around to building. It’s now marked for an overhaul or removal.

■ ■ ■

ePostcodes is a very simple site that gives our readers access to a simple Australian postcode API with various functions. It’s easy to create a fully functioning postcode search website based upon the information the API provides. In fact, this website is itself API-centric – meaning that all our own requests are made via the API.

This post will show you how to use the depreciated XML API to:

  • Calculate the Distance between two Australian Postal Codes.
  • Extract details on a single or multiple postcodes.
  • Search postal codes by name.
  • Find Postal Codes Within a Radius of Another Code.
  • Search Postal Codes Within a Radius of a Geographical Point.

For all API calls described below, the API URL is prefixed by http://api.epostcodes.com.au/ (as used in the linked examples).

A Brief History

Several years ago, we built a little postcode search site at AussiePostCodes.com (in fact, it was one of our first). ePostcodes is a natural variation on that early (uninspired) theme. AussiePostCodes was originally website was built to serve a single purpose but, since that time, it’s become evident that a more robust and scalable solution was necessary… not to mention the need for an API function that would assist us and others with other applications.

Considerations

For all calls to the API, consider the following:

  • The provided code is fairly ordinary and uses a simple text file cache (as described in this postsort of).
  • There are references to the term ‘zip’ multiple times in most of the provided functions. This was done simply because some of the code was copied from another one of our sites.
  • It’s best to cache results for no longer than a few days since we update data regularly.
  • Rate limiting applies to mitigate unreasonable requests. Errors are described below.
  • The PHP functions provided are examples only. More comprehensive code will be provided when we launch the zipAPI website.
  • Some results are truncated. While the API provides for paginated results, we’re reserving that functionality for a new website.
  • For all the latitude and longitude coordinates that we return, consider making them more readable with this function.
  • All the functions described in this post are on this page.

Calculate the Distance between Two Australian Postal Codes

This function will calculate the distance between two Australian Postal Codes. With an input of two postcodes, the returned XML includes the distance (in miles, kilometers and nautical miles), the two placenames, bspname (postal region), state codes and state.

Endpoint

api/distance/[code1]/[code2]/api.xml [ example ]

The XML returned when querying the distance between 2138 and 2135 is as follows [ XML ]:

XML Distance Response

XML Distance Response

An issue with Australian postcodes is that the same code can be used in multiple localities (in the example above, 2138 is the postal code for Liberty Grove, Concord West and Rhodes). For that reason, you can specify the placename in the API call. If you choose to use this functionality, you’ll have to convert the placename into a ‘slug’; it’s best to use something like the WordPress sanitize_titles_with_dashes function.

api/dist/[code1]/[place1]/[code2]/[place2]/api.xml [ example , example ]

For most situations, the first XML call is more than appropriate.

Get Single or Multiple Australian Postcodes

The XML response when querying the API for postal code details will return the postcode latitude, longitude, placename, bspname, state code and state. The API endpoint remains the same regardless of whether you’re querying just one or multiple postcodes.

Endpoint

api/codes/2138/api.xml or api/codes/2138,2000/api.xml

Note that when querying multiple postcodes, they’re included in the URL as a comma separated string.

The returned XML will be similar to this:

Multiple Postcodes

XML Response. Querying postcode 2138 and 2000

Search Australian Postal Codes by Name

Rather than searching by code, we can search for postal codes by partial or full name (with a wildcard option). The XML response will return the postcode latitude, longitude, placename, bspname, state code and state.

Endpoint

api/term/sydney/api.xml

In this case, the API will return only terms matching Sydney exactly. To use a wildcard search, use an underscore character before or after your text. For example, you can search for Sydney as sydney , _sydney , sydney_ or _sydney_ .

If you’re searching for a partial name (for example: syd), you must use the wildcard option (“syd_” or “_syd_”). For two-word suburbs, you should try to join each word with a “+” sign.

Find Postal Codes Within a Radius of Another Code

We can search for postal codes within a defined radius of another postal code. The XML response will return the postcode latitude, longitude, placename, bspname, state code, state and, most important, the distance from the origin. Keep in mind that multiple neighbouring suburbs may have the same code: we select only one.

Endpoint

api/nearby/[postcode]/[distance][unit]/api.xml

Search Postal Codes Within a Radius of a Geographical Point

We can search for postal codes within a defined radius of a geographical latitude/longitude position. As per the last response, the returned XML will return the postcode latitude, longitude, placename, bspname, state code, state and, most important, the distance from our geographical reference.

Endpoint

api/nearby/[postcode]/[distance][unit]/api.xml

Error Codes

We’ve mitigated the potential for abuse (since it’s a free service) by rate-limiting unreasonable requests. If you’re rate limited, you will see an error message as follows:

XML Error Message

Error message (0). Block for 13 seconds.

There are other errors. Generally speaking, anything other than a response of 200 is bad.