Get cities

Overview

Get the cities for the given country_code and state_code as {label, value} pairs, ordered by name. City lists rarely change, so the result is cached indefinitely under the key cities_list_v2_{country_code}_{state_code}. Repeat calls are served from that cache, so they stay fast and consistent. A change to the underlying reference data only appears once that cache entry is cleared; there is no automatic per-request expiry.

Prerequisites

• No authentication — this endpoint is public.
• Values for the required query parameters country_code and state_code:
  • country_code — ISO 3166-1 alpha-2 country code (e.g., US, CA, GB)
  • state_code — ISO 3166-2 subdivision code for the country (e.g., CA for California, ON for Ontario)

Base URL

Endpoint

GET /api/v1/address/cities

Authentication

• No bearer token required. This is a public reference endpoint.
• Who can call it: Anyone — no authentication or role scoping required. The same global list is available to all users.

Rate limit

• 100 requests/min.

Query parameters

• Query: country_code (string, required) — must be a known country code.
• Query: state_code (string, required) — must be a known state code.

Response

• data.data[] (array of objects) — cities for that state/country.
• value (integer) — city id.
• label (string) — city name.

200 Success · 200

{
  "data": {
    "data": [
      { "value": 1042, "label": "Los Angeles" },
      { "value": 1213, "label": "San Francisco" },
      { "value": 1305, "label": "San Diego" }
    ]
  }
}

Errors

Example request

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