List states

Overview

Get the states or regions in a country.

Use this after the user picks a country.

You'll need the country.

Returns states with their codes, sorted by name. Use a state's value as state_code in List cities.

Prerequisites

• A country_code, from List countries.

Base URL

Endpoint

GET /api/v1/address/states

Authentication

Public (no token)

• Anyone gets the same global list. A Partner or Account token may be sent, but none is needed.

Rate limit

100 requests per minute, counted per client IP address. See Rate limits.

Request parameters

Request body

None.

Request payload

None.

Response body

The payload is inside data.data: one entry per state.

Response payload

{
  "data": {
    "data": [
      {
        "value": "AL",
        "label": "Alabama"
      },
      {
        "value": "AK",
        "label": "Alaska"
      },
      {
        "value": "AS",
        "label": "American Samoa"
      },
      {
        "value": "AZ",
        "label": "Arizona"
      }
    ]
  }
}

Examples

Success payload

See Response payload (shortened; country_code=US returns every state and territory).

Error payload

422 country_code missing

{
  "message": "The country code field is required.",
  "errors": {
    "country_code": [
      "The country code field is required."
    ]
  }
}

422 Unknown country

{
  "message": "The selected country code is invalid.",
  "errors": {
    "country_code": [
      "The selected country code is invalid."
    ]
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/address/states?country_code=US" \
  --header 'Accept: application/json'