> ## 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.

# Destination Autocomplete

> Find normalized places, cities, and hotels for a hotel-search destination picker.

Use destination autocomplete to power the location picker before hotel search.
It returns normalized `place`, `city`, and `hotel` results, so your application
does not need separate destination data from each enabled supplier.

<Info>
  Cache successful autocomplete responses for **up to 48 hours**. Keep cache
  entries separate by environment and include every request input in the cache
  key: normalized query, `types`, `city_id`, `limit`, and `language`.
</Info>

## Build the Picker

<Steps>
  <Step title="Collect the query">
    Call the endpoint after the customer enters at least two characters.
    Debounce type-ahead input before sending a request.
  </Step>

  <Step title="Render the results">
    Display `display_name` as the main label and `subtext` as supporting
    context. Keep the selected result object until the search request is made.
  </Step>

  <Step title="Use the matching identifier">
    Send `city_id`, `hotel_id`, or `place_id` according to the result's `type`.
    Do not send `id`; it is a UI key rather than a hotel-search destination ID.
  </Step>
</Steps>

## Request Examples

<RequestExample>
  ```bash theme={null}
  curl "$UNIFYSTAYS_BASE_URL/destinations/autocomplete?q=dubai&types=place,city,hotel&limit=10" \
    -H "x-api-key: $UNIFYSTAYS_API_KEY" \
    -H "language: en"
  ```
</RequestExample>

After a customer chooses a city, use `city_id` to find hotels only within that
city:

<RequestExample>
  ```bash theme={null}
  curl "$UNIFYSTAYS_BASE_URL/destinations/autocomplete?q=mar&city_id=136711&limit=10" \
    -H "x-api-key: $UNIFYSTAYS_API_KEY" \
    -H "language: en"
  ```
</RequestExample>

## Use the Selection in Hotel Search

| Selected result type | Send as `destination.type` | Send as `destination.id` |
| -------------------- | -------------------------- | ------------------------ |
| `city`               | `city`                     | `city_id`                |
| `hotel`              | `hotel`                    | `hotel_id`               |
| `place`              | `place`                    | `place_id`               |

```json theme={null}
{
  "destination": {
    "type": "place",
    "id": 2930267
  }
}
```

## Response Example

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Destinations fetched successfully",
    "data": {
      "query": "dubai",
      "types_searched": ["place", "city", "hotel"],
      "total": 3,
      "results": [
        {
          "id": "place-2930267",
          "type": "place",
          "display_name": "Dubai",
          "subtext": "United Arab Emirates",
          "country_code": "AE",
          "city_id": 136711,
          "place_id": 2930267,
          "place_type": "region",
          "hotel_count": 10983
        },
        {
          "id": "city-136711",
          "type": "city",
          "display_name": "Dubai",
          "subtext": "United Arab Emirates",
          "country_code": "AE",
          "city_id": 136711
        },
        {
          "id": "hotel-10001",
          "type": "hotel",
          "display_name": "Example Hotel Dubai",
          "subtext": "5 stars - Dubai, United Arab Emirates",
          "country_code": "United Arab Emirates",
          "city_id": 136711,
          "hotel_id": "10001",
          "stars": 5
        }
      ]
    }
  }
  ```
</ResponseExample>

## Behavior and Caching

* Without `city_id`, city matches can start at two characters. Place and hotel
  matches start at three characters.
* With `city_id`, results are hotel-only and scoped to that city, even when
  `types` is also supplied.
* Render the returned order. The API balances place, city, and hotel results.
* Normalize the query by trimming whitespace and lowercasing it before building
  a cache key.
* Cache successful responses only. Autocomplete helps a customer choose a
  destination; it does not guarantee price, room availability, or bookability.

The OpenAPI section below provides the complete query parameter and response
field reference.


## OpenAPI

````yaml reference/openapi.json GET /destinations/autocomplete
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:
  /destinations/autocomplete:
    get:
      tags:
        - Destinations
      summary: Destination autocomplete
      description: >-
        Returns a mixed list of places, cities, and/or hotels whose names match
        the search query. Use the `types` parameter to restrict results to
        specific entity types. Results are presented in a balanced order across
        places, cities, and hotels. 


        Pass `city_id` to search hotels WITHIN one city (e.g. the user already
        picked Dubai and now types a hotel name): results become hotel-only,
        scoped to that city, and work from 2 characters. 


        **Usage in hotel search:** pass the returned `type` and the relevant id
        (`city_id` for type="city", `hotel_id` for type="hotel", or `place_id`
        for type="place") into the `destination` field of `POST
        /hotels/search`. 


        **Caching:** Cache successful responses for up to 48 hours. Include the
        environment and all query parameters in the cache key.
      operationId: DestinationAutocompleteController_autocomplete
      parameters:
        - name: q
          required: true
          in: query
          description: Search query string. Minimum 2 characters.
          schema:
            minLength: 2
            example: mum
            type: string
        - name: types
          required: false
          in: query
          description: >-
            Comma-separated list of result types to include. Omit to return all
            types (place + city + hotel).
          schema:
            example: place,city,hotel
            type: array
            items:
              type: string
              enum:
                - city
                - hotel
                - place
        - name: limit
          required: false
          in: query
          description: Maximum number of results to return. Default 10, max 20.
          schema:
            minimum: 1
            maximum: 20
            default: 10
            example: 10
            type: number
        - name: city_id
          required: false
          in: query
          description: >-
            Scope hotel suggestions to one city (id from a previous city
            autocomplete pick). When set, only hotels in that city are returned
            (city results are omitted) and the hotel search works from 2
            characters instead of 3.
          schema:
            example: 136711
            type: number
        - name: language
          description: Enter language code(ex. en)
          in: header
          schema: {}
      responses:
        '200':
          description: Autocomplete results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestinationAutocompleteResponseDto'
        '400':
          description: Bad request
components:
  schemas:
    DestinationAutocompleteResponseDto:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Destinations fetched successfully
        data:
          $ref: '#/components/schemas/DestinationAutocompleteDataDto'
      required:
        - success
        - message
        - data
    DestinationAutocompleteDataDto:
      type: object
      properties:
        query:
          type: string
          example: mum
        types_searched:
          type: array
          description: Types that were actually searched.
          example:
            - city
            - hotel
          items:
            type: string
            enum:
              - city
              - hotel
              - place
        total:
          type: number
          example: 4
        results:
          type: array
          items:
            $ref: '#/components/schemas/DestinationItemDto'
      required:
        - query
        - types_searched
        - total
        - results
    DestinationItemDto:
      type: object
      properties:
        id:
          type: string
          description: Unique key — prefixed with type for unambiguous UI keying.
          example: city-101
        type:
          type: string
          description: Result type.
          enum:
            - city
            - hotel
            - place
          example: city
        display_name:
          type: string
          description: Primary display name shown in the dropdown.
          example: Mumbai
        subtext:
          type: string
          description: Secondary line shown below the display name.
          example: Maharashtra, India
        country_code:
          type: string
          description: >-
            Country context for the result. City and place results use an ISO
            3166-1 alpha-2 code; hotel results can contain the property country
            label.
          example: IN
        city_id:
          type: number
          description: >-
            City master ID — always populated. For city results this is the city
            row id. For hotel results this is the hotel's city_id. For place
            results, use place_id in hotel search instead. Pass this as
            destination.id when type = "city" in the hotel search request.
          example: 101
        hotel_id:
          type: string
          description: >-
            Internal hotel_id — only present when type = "hotel". Pass this as
            destination.id when type = "hotel" in the hotel search request.
          example: '10001'
        stars:
          type: object
          description: Star rating — only present when type = "hotel".
          example: 5
        place_id:
          type: number
          description: >-
            Place id — only present when type = "place". Pass this as
            destination.id when type = "place" in the hotel search request.
          example: 2930267
        place_type:
          type: string
          description: >-
            Place level — only present when type = "place". One of: country,
            region, county, localadmin, locality, macrohood, neighborhood,
            microhood, custom_region.
          example: region
        hotel_count:
          type: number
          description: >-
            Number of bookable hotels under this place (whole subtree) — only
            present when type = "place". Render as e.g. "10,983 hotels".
          example: 10983
      required:
        - id
        - type
        - display_name
        - subtext
        - country_code
        - city_id
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Environment-specific API key created in the Unifystays portal

````