List locations

Page through every valid Australian suburb with its postcode and state. These are the suburb and postcode pairs a quote accepts.

GET /api/v5/locations
GET /api/v5/locations/page/{page}

No API key needed.

To find one suburb or postcode, use Search locations or Get locations by postcode instead.

Parameters

Parameter	In	Type	Description
`page`	path	integer	Page number, starting at 1. `/api/v5/locations` is page 1.
`limit`	query	integer	Rows per page, from 1 to 5000. Defaults to 1000. A larger value is treated as 5000, and anything that is not a positive number as 1000.

Rows are ordered by postcode, so page 1 starts with ACT and NT postcodes such as 0200 and 0800.

Example request

curl "https://api.transdirect.com.au/api/v5/locations/page/2?limit=3"

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

const { data, error } = await getApiV5LocationsPageByPage({
  path: { page: '2' },
  query: { limit: '3' },
});
if (!data) throw new Error(JSON.stringify(error));
console.log(data.locations.length, data.next_page);

For the first page, call getApiV5Locations({ query: { limit: '1000' } }).

Response

200 OK:

{
  "code": 200,
  "locations": [
    { "locality": "WAGAIT BEACH", "postcode": "0803", "state": "NT", "id": 5, "priority": 30 },
    { "locality": "PARAP", "postcode": "0804", "state": "NT", "id": 6, "priority": 55 },
    { "locality": "LEE POINT", "postcode": "0810", "state": "NT", "id": 12, "priority": 9 }
  ],
  "next_page": "https://api.transdirect.com.au/api/v5/locations/page/3?limit=3",
  "prev_page": "https://api.transdirect.com.au/api/v5/locations?limit=3"
}

Field	Type	Description
`code`	integer	Always `200`.
`locations`	array	The suburbs on this page.
`locations[].locality`	string	Suburb name, in capitals.
`locations[].postcode`	string	Four-digit postcode, with leading zeros.
`locations[].state`	string	State or territory code, for example `NSW`.
`locations[].id`	integer	Transdirect’s id for the suburb.
`locations[].priority`	integer	A ranking value Transdirect uses to order suggestions.
`next_page`	string	Full URL of the next page. Present only when this page is full, so stop when it is missing.
`prev_page`	string	Full URL of the previous page. Present from page 2.

Download every suburb at once

GET /api/v5/locations/all/

Returns the whole list in one response, {"count": 16386, "suburbs": [...]}, with the same fields as above. The response is over 1 MB and can be cached for 2 days (Cache-Control: public, max-age=172800). Use it to search suburbs in your own app without a request per keystroke. SDK function: getApiV5LocationsAll.

List countries

GET /api/v5/locations/countries

Returns every country Transdirect knows, with the two-letter code to send as country on an address:

[
  { "id": "13", "code": "AU", "name": "Australia", "postcode_status": "1" },
  { "id": "153", "code": "NZ", "name": "New Zealand", "postcode_status": "1" }
]

postcode_status is "1" when addresses in that country use postcodes. The list rarely changes and can be cached for a day. For a country’s states, use List states. SDK function: getApiV5LocationsCountries.

Errors

Status	Body	Cause
`400`	`{"error":"invalid_page"}`	`page` is not a whole number of 1 or more.
`302`		A `q` parameter was sent to `/api/v5/locations`. You are redirected to Search locations.

Try it

Open the API Explorer and find List valid suburbs (paged). No key is needed.