List cities

Overview

Get the cities in a state.

Use this to find the city_id for an address.

You'll need the state.

Returns cities with ids, sorted by name. Use a city's value as city_id, for example in Save the billing address.

Prerequisites

• A country_code, from List countries, and a state_code, from List states.

Base URL

Endpoint

GET /api/v1/address/cities

Authentication

Public (no token)

• Anyone gets the same global list.

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 city. An empty array when the state has no cities in that country.

Response payload

{
  "data": {
    "data": [
      {
        "value": 133434,
        "label": "Acalanes Ridge"
      },
      {
        "value": 133435,
        "label": "Acton"
      },
      {
        "value": 133436,
        "label": "Adelanto"
      }
    ]
  }
}

Examples

Success payload

A state code that isn't in the country (here country_code=AU&state_code=CA):

{
  "data": {
    "data": []
  }
}

Error payload

422 Codes missing

{
  "message": "The state code field is required. (and 1 more error)",
  "errors": {
    "state_code": [
      "The state code field is required."
    ],
    "country_code": [
      "The country code field is required."
    ]
  }
}

429 Too many requests

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

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'