Skip to content

Get locations by postcode

List the suburbs that belong to one Australian postcode, for example to fill a suburb drop-down once a user has entered a postcode.

GET /api/v5/locations/postcode/{postCode}

No API key needed.

Path parameters

Parameter	Type	Description
`postCode`	string	A four-digit Australian postcode, for example `2000` or `0800`.

Example request

curl https://api.transdirect.com.au/api/v5/locations/postcode/2000

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

const { data, error } = await getApiV5LocationsPostcodeByPostCode({
  path: { postCode: '2000' },
});
if (!data) throw new Error(JSON.stringify(error));
console.log(data.locations.map((place) => place.locality));

Response

200 OK:

{
  "locations": [
    { "locality": "PARLIAMENT HOUSE", "postcode": "2000", "state": "NSW" },
    { "locality": "MILLERS POINT", "postcode": "2000", "state": "NSW" },
    { "locality": "THE ROCKS", "postcode": "2000", "state": "NSW" },
    { "locality": "DAWES POINT", "postcode": "2000", "state": "NSW" },
    { "locality": "SYDNEY SOUTH", "postcode": "2000", "state": "NSW" },
    { "locality": "BARANGAROO", "postcode": "2000", "state": "NSW" },
    { "locality": "HAYMARKET", "postcode": "2000", "state": "NSW" },
    { "locality": "SYDNEY", "postcode": "2000", "state": "NSW" }
  ]
}

Field	Type	Description
`locality`	string	Suburb name, in capitals. Send it as the address `suburb` in a quote.
`postcode`	string	The postcode you asked for.
`state`	string	State or territory code.

The list is not alphabetical. Sort it yourself if you show it in a drop-down. A four-digit postcode that has no suburbs, such as 0000, returns {"locations": []}.

Errors

Status	Body	Cause
`400`	`{"success":false,"error":{"name":"ZodError","message":"..."}}`	`postCode` is not exactly four digits. The message says “postCode must be a four digit Australian postcode”.

Try it

Open the API Explorer and find List valid suburbs for a postcode. No key is needed.