RBA Cash Rate: 4.35% · 1AUD = 0.67 USD · Inflation: 4.1%  
Leading Digital Marketing Experts</strong | 1300 235 433 | Aggregation Enquires Welcome | Book Appointment
Example Interest Rates: Home Loan Variable: 5.69% (5.89%*) • Home Loan Fixed: 5.39% (6.67%*) • Fixed: 5.39% (6.67%*) • Variable: 5.69% (5.89%*) • Investment IO: 5.69% (6.52%*) • Investment PI: 5.49% (5.98%*)

Australia Postcode Search and API

Australia Postcode Search and API

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:

1
Array
2
(
3
    [status] => 200
4
    [message] => okay
5
    [code] => 200
6
    [data] => Array
7
        (
8
            [postcode] => 2138
9
            [locality] => CONCORD WEST, LIBERTY GROVE, RHODES
10
            [state] => NSW
11
            [comments] =>
12
            [deliveryoffice] => LIDCOMBE DELIVERY CENTRE
13
            [presortindicator] => 207
14
            [parcelzone] => N1
15
            [bspnumber] => 006
16
            [bspname] => PARRAMATTA
17
              => Delivery Area
18
            [latitude] => -33.8308601379
19
            [longitude] => 151.0875396729
20
        )
21
 
22
)

If 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.

Australia Postcode Search and API

A valid API Key will return a large amount of localised data.

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:

1
Array
2
(
3
    [status] => 200
4
    [message] => okay
5
    [code] => 200
6
    [page] => 1
7
    [num] => 10
8
    [total] => 4
9
    [results] => Array
10
        (
11
            [1] => Array
12
                (
13
                    [postcode] => 2137
14
                    [locality] => CONCORD
15
                    [state] => NSW
16
                    [comments] =>
17
                    [deliveryoffice] => LIDCOMBE DELIVERY CENTRE
18
                    [presortindicator] => 207
19
                    [parcelzone] => N1
20
                    [bspnumber] => 006
21
                    [bspname] => PARRAMATTA
22
                      => Delivery Area
23
                    [latitude] => -33.8835411072
24
                    [longitude] => 151.1138458252
25
                )
26
 
27
            [2] => Array
28
                (
29
                    [postcode] => 2138
30
                    [locality] => CONCORD WEST
31
                    [state] => NSW
32
                    [comments] =>
33
                    [deliveryoffice] => LIDCOMBE DELIVERY CENTRE ...

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:

1
Array
2
(
3
    [status] => 200
4
    [message] => Invalid request
5
    [code] => 400
6
    [errors] => Array
7
        (
8
            [0] => Invalid request. Letters, numbers, and spaces only.
9
            [1] => Search length must be a minimum of 3 characters.
10
        )
11
 
12
)

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.

1
Array
2
(
3
    [status] => 200
4
    [message] => okay
5
    [code] => 200
6
    [distance] => Array
7
        (
8
            [miles] => 19.81
9
            [kilometers] => 31.87
10
            [nautical] => 17.2
11
        )
12
 
13
    [data] => Array
14
        (
15
            [2138] => Array
16
                (
17
                    [postcode] => 2138
18
                    [locality] => CONCORD WEST, LIBERTY GROVE, RHODES
19
                    [state] => NSW
20
                    [comments] =>
21
                    [deliveryoffice] => LIDCOMBE DELIVERY CENTRE
22
                    [presortindicator] => 207
23
                    [parcelzone] => N1
24
                    [bspnumber] => 006
25
                    [bspname] => PARRAMATTA
26
                      => Delivery Area
27
                    [latitude] => -33.8308601379
28
                    [longitude] => 151.0875396729
29
                )
30
 
31
            [2557] => Array
32
                (
33
                    [postcode] => 2557
34
                    [locality] => CATHERINE FIELD, ROSSMORE
35
                    [state] => NSW
36
                    [comments] =>
37
                    [deliveryoffice] => NARELLAN DC
38
                    [presortindicator] => 205
39
                    [parcelzone] => N1
40
                    [bspnumber] => 014
41
                    [bspname] => CAMPBELLTOWN
42
                      => Delivery Area
43
                    [latitude] => -33.9457702637
44
                    [longitude] => 150.7711639404
45
                )
46
 
47
        )
48
 
49
)

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):

1
(
2
    [status] => 200
3
    [message] => Okay. 10 results max returned within 30 klms.
4
    [code] => 200
5
    [total] => 10
6
    [results] => Array
7
        (
8
            [0] => Array
9
                (
10
                    [postcode] => 2139
11
                    [locality] =>
12
                    [state] => NSW
13
                    [comments] =>
14
                    [deliveryoffice] => LIDCOMBE DELIVERY CENTRE
15
                    [presortindicator] => 207
16
                    [parcelzone] => N1
17
                    [bspnumber] => 006
18
                    [bspname] => PARRAMATTA
19
                      => LVR
20
                    [latitude] => -33.8370094299
21
                    [longitude] => 151.0924987793
22
                    [distance] => Array
23
                        (
24
                            [kilometers] => 0
25
                            [miles] => 0
26
                            [nautical] => 0
27
                        )
28
 
29
                )
30
 
31
            [1] => Array
32
                (
33
                    [postcode] => 2138
34
                    [locality] =>
35
                    [state] => NSW
36
                    [comments] =>
37
                    [deliveryoffice] => LIDCOMBE DELIVERY CENTRE
38
                    [presortindicator] => 207
39
                    [parcelzone] => N1
40
                    [bspnumber] => 006
41
                    [bspname] => PARRAMATTA
42
                      => Delivery Area
43
                    [latitude] => -33.8308601379
44
                    [longitude] => 151.0875396729
45
                    [distance] => Array
46
                        (
47
                            [kilometers] => 0.823
48
                            [miles] => 0.511
49
                            [nautical] => 0.444
50
                        )
51
 
52
                ) ...

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.

■ ■ ■

 
Download our complimentary 650-page guide on marketing for mortgage brokers. We'll show you exactly how we generate billions in volume for our clients.
Finance Guide, Cropped Top and Bottom
  Timezone: 1 · [ CHANGE ]

RELATED READING

Like this article?

Share on Facebook
Share on Twitter
Share on Linkdin
Share on Pinterest

Leave a comment