One of our early online strategies (dating back over 12 years) involved building lots of websites that provided search features for differing types of data. The idea was that if a website covered its cost, having hundreds - or even thousands - of them would return a good income. While the sites were useful (we always steered clear of anything spammy), they were super-simple in nature to avoid the ongoing time-cost and support. Of course, as our early business model scaled in size that model soon became unviable because of associated time-sacrifice and effort that came with maintaining them. As other areas of our business grew, it became apparent we'd have to simply do away with the majority of our coveted online arsenal. That said, there are a few dozen sites that we'll keep. One of those that survived the cull is also the very first site we ever put an AdSense advert on (Edit: December 2017, we've since let the domain lapse).
The website, built in 2005, was born into a time when MySpace was the premium social network, the iPhone was nothing more than an idea, and building a sitemap meant nothing more than a page full of HTML links. Despite the massive advancements we've seen in tech since then, APC occupied its little corner of cyberspace without anything more than an occasional glance.
About 12 months after we built the aforementioned service we built another site with similar functionality (epostcodes.com.au
) to test a few features that we then built into another site, iToilet.com.au
(thanks, George Costanza). The similarity/overlap in website features and design might give you an indication of how we quickly accrued over 800 sites. Both of these sites are themselves due for a mobile-optimized update
It's only now that we've revisited AussiePostCodes and provided a necessary update. Because we widely use postal data on standalone sites and within our media platform, we built an API that would work off a central data source (Edit: December 2017: we'll be porting the entire site over to another domain sometime soon).
Postcode API
We built two simple XML APIs in the past; one for epostcodes.com.au (Australia), and another for postcodez.com (USA). We've steered away from providing any XML APIs in the future and are instead relying on the platform-agnostic JSON responses. It's this post that'll detail the basic responses provided by the new API.
Postcode Response
Endpoint: http://api.beliefmedia.com/postcodes/{postcode}.json. If an API key is provided, it should be done so as follows: http://api.beliefmedia.com/postcodes/{apikey}/{postcode}.json.
Any request for a postcode must be numeric and 4 digits long, and it's expected that the error checking will be done by you (requesting anything else will return a server 404 error). An example decoded response is as follows:
=> Delivery AreaIf an optional API is provided an image of the postal region will be returned along with 30 other points of interest nearest to the define latitude and longitude. Because the returned data is intended to be used by us, there's a number of other parameters that'll return other data, such as nearest banks, nearest real-estate agents, local mortgage brokers, and so on. This gives us a central means of connecting data from our satellite websites into our media and marketing management system.
Searching Results
The search response will include paginated results matching your criteria.
Endpoint: http://api.beliefmedia.com/postcodes/search.php?s=concord. An example response (partial) is as follows:
Queries should be checked on your end. Generally, alphanumeric characters and spaces are permitted.
The status message only means we're returning a response. It's the code value that'll determine if a valid request was made or not. Generally, anything other than 200 is bad. A 404 error means 'not found', 400 means 'Invalid query', 429 means 'Unregistered API Quota exceeded', and so on. If an error is returned, it generally takes on the following form:
Errors are returned as an array or a single value. A check should be made before returning a result. Note that a minimum of three search characters is required.
Distance Between Two Postcodes
The distance between two valid and unique postal codes may be returned with the following endpoint: http://api.beliefmedia.com/postcodes/{source}-{destination}/distance.json. If registered access is made, use the following: http://api.beliefmedia.com/postcodes/{apikey}/{source}-{destination}/distance.json. The example response below shows the distance in various units between Sydney's 2138 and 2557.
A standard error response will be returned if either of the postcodes is invalid or doesn't exist. A server 404 error will be returned for unregistered users if the URL isn't structured correctly. Registered users will see an error message. The results won't be overly accurate until we regenerate the coordinates.
Nearby Postal Areas
Postal areas near to a postcode may be returned via the endpoint of http://api.beliefmedia.com/postcodes/near/2138.json. A maximum of 10 results within a 30 kilometer radius is made available to unregistered users. A response will unfold and look a little to the following (only two results are shown):
Registered users may access paginated responses with varying distances from source. Details are in the client area. Generally, the query URL is near/{apikey}/{postcode}.json for a basic response, and near/{apikey}/{distance}/{postcode}.json for a defined distance from the source.
The response includes the query postcode. The nearby feature should be used with caution until location data is refreshed.
Searching by Geographics Coordinates
Given a known latitude and longitude, unregistered users may return up to 10 nearest postcodes within 30 kilometers. Endpoint is as follows: postcodes/geo/{latitude}/{longitude}/geo.json. The data will unfold in the same manner as the 'nearest postcode' response above. Registered users may query by distance with a paginated response (no limit).
Again, until we geocode locations again, data should be used with caution.
Reliability of Data
We can't provide any guarantee on the validity or accuracy of any of the data returned. If you're after something more accurate, use the official API provided by Australia Post. We've compiled the data we use from multiple sources and we're happy to use it ourselves. Use at your own risk.
A statement made on Data.gov.au 
details the stringent licensing of postal data in an effort to enforce usage of the Australia Post system. Ironically, it's their decision not to make the Government data freely available that has invariably led to multiple 'invalid' sources.
Google Geocoding
We built the API for features other than postal data; we generally don't use it to validate address data in forms. We use a single field that'll populate with an addresses (via a Google API) with each character keystroke. The simple form will invariably improve upon contact conversions and is far easier to use. We'll share details another time.
Considerations
- All our data sources are progressively being made available via their own API... and this was next on the list. Part of the motivation was to demonstrate to clients how easily certain types of their own data might be made available to their clients or, in the case of franchise operations, how one source of information might be shared to multiple stakeholders (an example is our extensive library of bank information and product updates intended for mortgage brokers, and made available to all our finance clients).
- There are numerous other geo-relevant API libraries available in our client area.
- The AussiePostCodes source code is available as a download from the client area.
