Skip to main content

Get States & Cities

Returns valid state and city values for a country.

Endpoint​

GET /v1/country/list

Request​

Header Parameters​

ParameterTypeRequiredExampleDescription
AuthorizationstringYesBearer YOUR_ACCESS_TOKENBearer token used for authentication.

Query Parameters​

ParameterTypeRequiredDescription
countrystringYesCountry name or ISO 3166-1 alpha-2 code (e.g. HK).

Example request​

curl -X GET "${API_URL}/v1/country/list?country=HK" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Responses​

200 Success​

200 Success

Response schema: application/json
data.countries
array
Information of matched country.
Expand for item fields.
code
string
ISO 3166-1 alpha-2 country code.
Example: HK
name
string
Country full name.
Example: Hong Kong
states
array
List of states for matched country.
Expand for item fields.
name
string
State, province, or district name.
cities
array
List of cities under this state.
Expand for item fields.
name
string
City name.
data.message
string
Informational message.

Response sample

{
  "data": {
    "countries": [
      {
        "code": "HK",
        "name": "Hong Kong",
        "states": [
          {
            "name": "Central and Western",
            "cities": [
              { "name": "Central" },
              { "name": "Sheung Wan" }
            ]
          },
          {
            "name": "Eastern District",
            "cities": [
              { "name": "North Point" },
              { "name": "Quarry Bay" }
            ]
          }
        ]
      }
    ],
    "message": "OK"
  }
}

400 Bad Request​

400 Bad Request

Response schema: application/json
code
string
Error code
Example: 400000
code_reason
string
Error reason.
Example: BAD_REQUEST
message
string
Human-readable message.
Example: country parameter is required

Response sample

{
  "error": {
    "code": "400000",
    "code_reason": "BAD_REQUEST",
    "message": "country parameter is required"
  }
}

401 Unauthorized​

401 Unauthorized

Response schema: application/json
code
string
Error code.
Example: 401000
code_reason
string
Error reason.
Example: UNAUTHORIZED
message
string
Human-readable message.
Example: Unauthorized

Response sample

{
  "error": {
    "code": "401000",
    "code_reason": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

403 Forbidden​

403 Forbidden

Response schema: application/json
error
json-string
Access forbidden for this resource.

404 Not Found​

404 Not Found

Response schema: application/json
error
json-string
Resource or endpoint not found.

500 Failure​

500 Failure

Response schema: application/json
code
string
Error code
Example: 500999
code_reason
string
Error reason.
Example: API_ERROR
message
string
Human-readable message.
Example: Api Error, please contact customer service

Response sample

{
  "error": {
    "code": "500999",
    "code_reason": "API_ERROR",
    "message": "Api Error, please contact customer service"
  }
}