List Cities

Retrieve the active city catalogue with search, country filtering, sorting, and pagination.

GET /master-data/cities

curl "$UNIFYSTAYS_BASE_URL/master-data/cities?search=dubai&country_code=AE&page=1&limit=20" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

200

{
  "success": true,
  "message": "Cities fetched successfully",
  "data": {
    "items": [
      {
        "id": 1,
        "city": "Mumbai",
        "country_name": "India",
        "country_code": "IN",
        "is_active": true
      }
    ],
    "meta": {
      "total": 250,
      "page": 1,
      "limit": 20,
      "totalPages": 13
    }
  }
}

Use this endpoint when your product needs a browsable or administrative city catalogue. For a customer-facing destination picker, prefer Destination Autocomplete, which returns places, cities, and hotels ranked for the entered text.

Request Example

curl "$UNIFYSTAYS_BASE_URL/master-data/cities?search=dubai&country_code=AE&page=1&limit=20" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

Use the Response

The response is paginated. Use its items for a city catalogue and use the city identifier from a selected result as destination.id with destination.type: "city" when calling Search Hotels.

City data identifies destinations; it is not a guarantee that a hotel is available for a particular stay. Continue with hotel search and room options for live shopping data.

The OpenAPI section below documents every filter, sort option, pagination field, and response property.

Authorizations

x-api-key · string · header · required

Environment-specific API key created in the Unifystays portal

Headers

Query Parameters

search · string

Search by city name or country name (case-insensitive)

Example:

"Mumbai"

country_code · string

Filter by ISO 3166-1 alpha-2 country code

Required string length: 2 - 3

Example:

"IN"

sort_by · enum<string> · default: city

Field to sort by

Available options: city, country_name, country_code

sort_order · enum<string> · default: ASC

Sort direction

Available options: ASC, DESC

page · number · default: 1

Page number (1-based)

Required range: x >= 1

Example:

1

limit · number · default: 20

Number of results per page (max 200)

Required range: 1 <= x <= 200

Example:

20

Response

200 - application/json

Cities fetched successfully

success · boolean · required

Example:

true

message · string · required

Example:

"Cities fetched successfully"

data · object · required

Show child attributes