Destination Autocomplete

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

GET /destinations/autocomplete

curl "$UNIFYSTAYS_BASE_URL/destinations/autocomplete?q=dubai&types=place,city,hotel&limit=10" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

{
  "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
      }
    ]
  }
}

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.

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.

Build the Picker

1. Collect the query

   Call the endpoint after the customer enters at least two characters. Debounce type-ahead input before sending a request.

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

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

Request Examples

curl "$UNIFYSTAYS_BASE_URL/destinations/autocomplete?q=dubai&types=place,city,hotel&limit=10" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

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

curl "$UNIFYSTAYS_BASE_URL/destinations/autocomplete?q=mar&city_id=136711&limit=10" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

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

{
  "destination": {
    "type": "place",
    "id": 2930267
  }
}

Response Example

{
  "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
      }
    ]
  }
}

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.

Authorizations

x-api-key · string · header · required

Environment-specific API key created in the Unifystays portal

Headers

Query Parameters

q · string · required

Search query string. Minimum 2 characters.

Minimum string length: 2

Example:

"mum"

types · enum<string>[]

Comma-separated list of result types to include. Omit to return all types (place + city + hotel).

Available options: city, hotel, place

Example:

"place,city,hotel"

limit · number · default: 10

Maximum number of results to return. Default 10, max 20.

Required range: 1 <= x <= 20

Example:

10

city_id · number

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.

Example:

136711

Response

200

application/json

Autocomplete results

success · boolean · required

Example:

true

message · string · required

Example:

"Destinations fetched successfully"

data · object · required

Show child attributes