Search locations

Find valid suburb and postcode pairs from what a user has typed, for example to power a suburb field that suggests matches.

GET /api/v5/locations/search?q={text}

No API key needed.

Query parameters

Parameter	Type	Description
`q`	string	The start of a suburb name or postcode, for example `melb` or `30`. Matching ignores case.
`limit`	integer	Maximum rows, from 1 to 5000. Defaults to 100 when `q` is set. A value outside that range returns `400`.

Leave out q and you get the first 1000 suburbs by postcode followed by every country, as {id, country_code, country_name} rows. Send q for suburb suggestions.

Example request

curl "https://api.transdirect.com.au/api/v5/locations/search?q=melbourne&limit=3"

import { getApiV5LocationsSearch } from '@transdirect/api-sdk';

const { data, error } = await getApiV5LocationsSearch({
  query: { q: 'melbourne', limit: 3 },
});
if (!data) throw new Error(JSON.stringify(error));
for (const place of data.locations) console.log(place);

Response

200 OK:

{
  "locations": [
    { "locality": "MELBOURNE", "postcode": "3000", "state": "VIC", "id": 5582, "priority": 18601 },
    { "locality": "MELBOURNE", "postcode": "3001", "state": "VIC", "id": 5583, "priority": 611 },
    { "locality": "MELBOURNE", "postcode": "3004", "state": "VIC", "id": 5586, "priority": 1520 }
  ]
}

Field	Type	Description
`locality`	string	Suburb name, in capitals. Send it as the address `suburb` in a quote.
`postcode`	string	Four-digit postcode, with leading zeros.
`state`	string	State or territory code.
`id`	integer	Transdirect’s id for the suburb.
`priority`	integer	A ranking value Transdirect uses to order suggestions.

Results are ordered by postcode. A search that matches nothing returns {"locations": []}. A name can match in several states and postcodes, so let the user pick the right row and send its locality, postcode and state together.

Street address suggestions

Two more endpoints help users enter a full Australian street address. Neither needs a key.

GET /api/v5/locations/address-suggestions?q={text}

Send at least 3 characters of an address. Returns up to 10 matches:

{
  "suggestions": [
    { "description": "1 MARKET ST, SYDNEY NSW 2000", "placeId": "GANSW706039831" },
    { "description": "SUITE 1, 1 MARKET ST, SYDNEY NSW 2000", "placeId": "GANSW710282080" }
  ]
}

Only Australian addresses are suggested. Fewer than 3 characters, or a country other than AU, returns an empty list. SDK function: getApiV5LocationsAddressSuggestions.

GET /api/v5/locations/address-details?pid={placeId}

Turns a chosen suggestion into address fields:

{
  "fields": {
    "unit": "",
    "streetNumber": "1",
    "street": "MARKET",
    "streetType": "ST",
    "address": "1 MARKET ST",
    "suburb": "SYDNEY",
    "state": "NSW",
    "postcode": "2000",
    "country": "AU"
  }
}

Use address, suburb, state, postcode and country for the quote address. An unknown pid returns 404 {"error":"address_not_found","message":"Address details were not found."}. SDK function: getApiV5LocationsAddressDetails.

Errors

Status	Body	Cause
`400`	`{"success":false,"error":{"name":"ZodError","message":"..."}}`	`limit` is not a whole number from 1 to 5000.

Try it

Open the API Explorer and find Search valid suburbs and postcodes. No key is needed.