API Documentation

'Australian Suburbs' provides free API endpoints to interact with postcode and suburb data. The functionality includes validating postcode-suburb combinations, retrieving suburbs by postcode, and fetching suburb suggestions based on a search term.

1. Validate Postcode-Suburb Combination

This endpoint validates if the provided postcode and locality combination is valid.

Request
GET https://australiansuburbs.au/api/validate?postcode={postcode}&suburb={suburb}
Parameters
  • postcode: A 4-digit postcode (numeric).
  • suburb: The name of the suburb, case-insensitive.
Response

{
    "valid": true
}
Possible Error Response

{
    "error": "Both postcode and suburb are required."
}
Status Codes
  • 200 OK: Valid combination.
  • 400 Bad Request: Missing postcode or locality parameter.

2. Get Suburbs by Postcode

This endpoint retrieves the suburb or suburbs and state associated with a given postcode. Multiple records may be returned for the same postcode.

Request
GET https://australiansuburbs.au/api/lookup_postcode?postcode={postcode}
Parameters
  • postcode: A 4-digit postcode to search for suburbs.
Response

{
    "postcode": "4128",
    "suburbs": [
        "KIMBERLEY PARK",
        "LOGAN HYPERDOME BC",
        "SHAILER PARK",
        "TANAH MERAH"
    ],
    "state": "QLD"
}
Possible Error Response

{"error":"No data found for this postcode."}
Status Codes
  • 200 OK: Localities successfully retrieved for the postcode.
  • 404 Not Found: Invalid or missing postcode.

3. Get Suburb Suggestions

This endpoint provides suburb suggestions based on a partial string. It returns suburb name, state and their associated postcodes.

Request
GET https://australiansuburbs.au/api/lookup_suburb?search={search}
Parameters
  • search: The search string, which can be a postcode or a partial/full locality name.
Response

[
    {
        "locality": "PLACID HILLS",
        "postcode": 4343,
        "state": "QLD"
    },
    {
        "locality": "PLAINBY",
        "postcode": 4355,
        "state": "QLD"
    },
    {
        "locality": "PLAINLAND",
        "postcode": 4341,
        "state": "QLD"
    }
]
Possible Error Response

{
    "error": "No matching suburbs found."
}
Status Codes
  • 200 OK: Suburb suggestions successfully retrieved.
  • 400 Bad Request: Missing or invalid search term.

General Error Handling

All APIs will return appropriate HTTP status codes and error messages for invalid requests:

  • 200 OK: The request was successful.
  • 400 Bad Request: Invalid parameters, missing required fields, or incorrect input.
  • 500 Internal Server Error: A server-side error occurred during processing.

Rate Limiting & Authentication

This API does not currently require authentication but is IP rate limited to prevent abuse:

  • 1000 requests per hour per IP address.
  • 100 requests per minute.

Abuse of this API may result in an IP ban. If you require whitelisting or rate increased with an explanation, please get in touch with us at [email protected]

This API uses opensource community derived data NOT approved or created by Australia Post. It may contain errors and should NOT be used commercially and be treated 'as is'.