Location Data — List Cities by State

Returns a list of all cities within a specific state or province. You must provide the stateId as a path parameter. This API is typically used to populate city dropdowns when selecting an address or location.

Limitations: The list is static and may not include newly formed administrative regions.

GET{gateway}/us/api/v1/cities/{stateId}

Payload

Attribute	Type	Description	Required
stateId	Integer	ID of the state for which the list of cities is to be fetched. Passed as a path parameter.	Yes

Response

Attribute	Type	Description
data	Array<Object>	List of city objects.
data[].id	Integer	City ID.
data[].name	String	City name.
data[].latitude	String	Latitude of the city.
data[].longitude	String	Longitude of the city.
data[].country	Object	Parent country details for the city.
data[].country.id	Integer	Country ID.
data[].country.name	String	Country name.
data[].country.iso2	String	ISO 3166-1 alpha-2 code.
data[].country.phoneCode	String	Country calling code.
data[].country.capital	String	Country capital city.
data[].country.currency	String	Currency code (e.g., PKR).
data[].country.currencySymbol	String	Currency symbol (e.g., ₨).
data[].country.region	String	Geographic region.
data[].country.latitude	String	Latitude of the country center.
data[].country.longitude	String	Longitude of the country center.
data[].country.nationality	String	Demonym/nationality.
data[].state	Object	State or province information of the city.
data[].state.id	Integer	State ID.
data[].state.name	String	State or province name.
data[].state.latitude	String	Latitude of the state.
data[].state.longitude	String	Longitude of the state.
data[].state.country	Object	Nested country details (same as data[].country).

200 — SUCCESS

{
  "data": [
    {
      "id": 85475,
      "name": "Islamabad",
      "country": {
        "createdAt": "2025-01-21T14:13:39.716+00:00",
        "id": 167,
        "name": "Pakistan",
        "iso2": "PK",
        "phoneCode": "92",
        "capital": "Islamabad",
        "currency": "PKR",
        "currencySymbol": "₨",
        "region": "Asia",
        "latitude": "70.00000000",
        "longitude": "30.00000000",
        "nationality": "Pakistani"
      },
      "state": {
        "createdAt": "2025-01-21T14:13:40.402+00:00",
        "id": 3169,
        "country": {
          "createdAt": "2025-01-21T14:13:39.716+00:00",
          "id": 167,
          "name": "Pakistan",
          "iso2": "PK",
          "phoneCode": "92",
          "capital": "Islamabad",
          "currency": "PKR",
          "currencySymbol": "₨",
          "region": "Asia",
          "latitude": "70.00000000",
          "longitude": "30.00000000",
          "nationality": "Pakistani"
        },
        "latitude": "33.72049970",
        "longitude": "73.04052770",
        "name": "Islamabad Capital Territory"
      },
      "latitude": "33.72148000",
      "longitude": "73.04329000"
    }
  ]
}

400 — FAILED

{
  "code": 1000,
  "message": "Invalid payload. Please check your request.",
  "type": "INVALID_PAYLOAD",
  "errors": [
    {
      "key": "stateId",
      "reason": "Invalid value provided."
    }
  ]
}

Location Data — List States by Country Manage KYC