List states

List a country’s states or regions, and whether an address in that country needs a state and a postcode. Use it to build address forms for international shipments.

GET /api/v5/locations/states?countryCode={code}

No API key needed.

Query parameters

Parameter	Type	Description
countryCode	string	Two-letter country code, for example AU or NZ. Case does not matter. Get codes from List countries.

The parameter is countryCode. Any other name, such as country, is ignored and you get the empty result below.

Example request

curl "https://api.transdirect.com.au/api/v5/locations/states?countryCode=AU"

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

const { data, error } = await getApiV5LocationsStates({
  query: { countryCode: 'AU' },
});
if (!data) throw new Error(JSON.stringify(error));
console.log(data.states, data.state_required, data.postcode_required);

Response

200 OK:

{
  "states": [
    { "code": "ACT", "name": "Australian Capital Territory" },
    { "code": "NSW", "name": "New South Wales" },
    { "code": "NT", "name": "Northern Territory" },
    { "code": "QLD", "name": "Queensland" },
    { "code": "SA", "name": "South Australia" },
    { "code": "TAS", "name": "Tasmania" },
    { "code": "VIC", "name": "Victoria" },
    { "code": "WA", "name": "Western Australia" }
  ],
  "state_required": true,
  "postcode_required": true
}

Field	Type	Description
states	array	The country’s states or regions, sorted by name.
states[].code	string	The code to send as the address state.
states[].name	string	The name to show.
state_required	boolean	Whether an address in this country needs a state.
postcode_required	boolean	Whether an address in this country needs a postcode.

A missing, blank or unknown countryCode returns 200 with an empty result:

{ "states": [], "state_required": false, "postcode_required": false }

Try it

Open the API Explorer and find List states for a country. No key is needed.

Related

• List locations
• Search locations