Note that the features described below are mainly retired. Various endpoints remain for specific applications but should be considered deprecated. Refere to our JSON API and WordPress plugin.
■ ■ ■
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 and we've since let it expire). 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 post... sort 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 ]:
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.
, 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:
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:
There are other errors. Generally speaking, anything other than a response of 200 is bad.
