Search locations

Endpoint

GET /api/locations/search

Searches for locations matching a query string. You can search by suburb name, postcode, or a prefix of either.

Query parameters

Parameter	Type	Required	Description
`q`	string	No	Search query (suburb name, postcode, or partial prefix). If omitted, the full locations catalogue is returned (large payload).

Request

# Search by suburb name
curl -X GET \
  -H "Content-Type: application/json" \
  "https://www.transdirect.com.au/api/locations/search?q=melbourne"

# Search by postcode
curl -X GET \
  -H "Content-Type: application/json" \
  "https://www.transdirect.com.au/api/locations/search?q=3000"

Response

A successful response returns a 200 status code with an envelope containing a locations array (not a bare array):

{
  "locations": [
    {
      "id": 100,
      "locality": "MELBOURNE",
      "postcode": "3000",
      "state": "VIC",
      "priority": 1
    },
    {
      "id": 101,
      "locality": "EAST MELBOURNE",
      "postcode": "3002",
      "state": "VIC",
      "priority": 1
    }
  ]
}

For historical compatibility, country rows may also appear in the same array with a different shape (country_code, country_name) when the full catalogue is loaded.

Location object

Field	Type	Description
`id`	integer	Suburb row id
`locality`	string	Suburb or locality name
`postcode`	string	Four-digit Australian postcode
`state`	string	State or territory abbreviation
`priority`	integer	Sort priority within the postcode