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
}
]
}
}
Destination & master data
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
After a customer chooses a city, use
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"
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 whentypesis 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.
Authorizations
Environment-specific API key created in the Unifystays portal
Headers
Query Parameters
Search query string. Minimum 2 characters.
Minimum string length:
2Example:
"mum"
Comma-separated list of result types to include. Omit to return all types (place + hotel).
Available options:
hotel, place Example:
"place,hotel"
Maximum number of results to return. Default 10, max 20.
Required range:
1 <= x <= 20Example:
10