> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifystays.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Cities

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

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

## Request Example

<RequestExample>
  ```bash theme={null}
  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"
  ```
</RequestExample>

## 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](/api-reference/search-hotels).

<Info>
  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.
</Info>

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


## OpenAPI

````yaml reference/openapi.json GET /master-data/cities
openapi: 3.0.0
info:
  title: Unifystays API
  description: >-
    One unified hotel API across suppliers. Integrate once, then enable and
    manage suppliers from the Unifystays portal.
  version: '1.0'
  contact: {}
servers:
  - url: https://api-sandbox.unifystays.com
    description: Sandbox
  - url: https://api.unifystays.com
    description: Production
security:
  - x-api-key: []
tags: []
paths:
  /master-data/cities:
    get:
      tags:
        - Master Data
      summary: List cities
      description: >-
        Returns a paginated list of active cities. Supports free-text search on
        city name or country name, and filtering by country code.
      operationId: CityController_listCities
      parameters:
        - name: search
          required: false
          in: query
          description: Search by city name or country name (case-insensitive)
          schema:
            type: string
            example: Mumbai
        - name: country_code
          required: false
          in: query
          description: Filter by ISO 3166-1 alpha-2 country code
          schema:
            minLength: 2
            maxLength: 3
            example: IN
            type: string
        - name: sort_by
          required: false
          in: query
          description: Field to sort by
          schema:
            default: city
            type: string
            enum:
              - city
              - country_name
              - country_code
        - name: sort_order
          required: false
          in: query
          description: Sort direction
          schema:
            default: ASC
            type: string
            enum:
              - ASC
              - DESC
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of results per page (max 200)
          schema:
            minimum: 1
            maximum: 200
            default: 20
            example: 20
            type: number
        - name: language
          description: Enter language code(ex. en)
          in: header
          schema: {}
      responses:
        '200':
          description: Cities fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CityListResponseDto'
components:
  schemas:
    CityListResponseDto:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Cities fetched successfully
        data:
          $ref: '#/components/schemas/CityListDataDto'
      required:
        - success
        - message
        - data
    CityListDataDto:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CityResponseDto'
        meta:
          $ref: '#/components/schemas/CityListMetaDto'
      required:
        - items
        - meta
    CityResponseDto:
      type: object
      properties:
        id:
          type: number
          example: 1
        city:
          type: string
          example: Mumbai
        country_name:
          type: string
          example: India
        country_code:
          type: string
          example: IN
        is_active:
          type: boolean
          example: true
      required:
        - id
        - city
        - country_name
        - country_code
        - is_active
    CityListMetaDto:
      type: object
      properties:
        total:
          type: number
          example: 250
        page:
          type: number
          example: 1
        limit:
          type: number
          example: 20
        totalPages:
          type: number
          example: 13
      required:
        - total
        - page
        - limit
        - totalPages
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Environment-specific API key created in the Unifystays portal

````