Destination Autocomplete

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

{
  "success": true,
  "message": "Destinations fetched successfully",
  "data": {
    "query": "dubai",
    "types_searched": ["place", "hotel"],
    "total": 2,
    "results": [
      {
        "id": "place-2930267",
        "type": "place",
        "display_name": "Dubai",
        "subtext": "United Arab Emirates",
        "country_code": "AE",
        "place_id": 2930267,
        "place_type": "region",
        "category": "city",
        "hotel_count": 10983
      },
      {
        "id": "hotel-10001",
        "type": "hotel",
        "display_name": "Example Hotel Dubai",
        "subtext": "5★ · Dubai, AE",
        "country_code": "AE",
        "hotel_id": "10001",
        "stars": 5
      }
    ]
  }
}

GET

destinations

autocomplete

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

{
  "success": true,
  "message": "Destinations fetched successfully",
  "data": {
    "query": "dubai",
    "types_searched": ["place", "hotel"],
    "total": 2,
    "results": [
      {
        "id": "place-2930267",
        "type": "place",
        "display_name": "Dubai",
        "subtext": "United Arab Emirates",
        "country_code": "AE",
        "place_id": 2930267,
        "place_type": "region",
        "category": "city",
        "hotel_count": 10983
      },
      {
        "id": "hotel-10001",
        "type": "hotel",
        "display_name": "Example Hotel Dubai",
        "subtext": "5★ · Dubai, AE",
        "country_code": "AE",
        "hotel_id": "10001",
        "stars": 5
      }
    ]
  }
}

Destination autocomplete is the first call in the booking flow: search → rooms → prebook → book → manage. Call it while the guest types in a “where to?” box. It returns a short, balanced list of places (countries, regions, cities, areas, airports, stations, attractions) and hotels. The item the guest picks becomes the destination of Search Hotels. Because the list is already normalized, you do not need separate destination data from each supplier. Hotel suggestions only include properties you can actually search: hotels that are bookable through at least one supplier enabled for your organization in the environment you call.

Sandbox only has hotels in 12 test cities: Paris, Los Angeles, Dubai, Rome, Naples, Istanbul, Tokyo, Bangkok, Chiang Mai, New Delhi, Ho Chi Minh City and Marrakech. A query for any other destination (for example q=london) returns an empty list in Sandbox. That is expected. Use IDs from the same environment you search in, because an ID copied from Production may return nothing in Sandbox. Contact support if you need a specific city in Sandbox.

Build the picker

Collect the query

Send a request once the guest has typed at least 3 characters. The API accepts 2 characters but returns an empty list below 3. Debounce keystrokes (for example 200 to 300 ms) before calling.

Render the results

Show display_name as the label and subtext as the second line. Use category (places) for an icon and hotel_count for “10,983 hotels”. Keep the order the API returns: places and hotels are already balanced.

Keep the selected result

Store the whole selected item until the guest submits the search. You need its type plus place_id or hotel_id.

Use the matching identifier

Send type and the matching ID as destination in Search Hotels. Never send id: it is only a UI key.

Request example

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

Response example

{
  "success": true,
  "message": "Destinations fetched successfully",
  "data": {
    "query": "dubai",
    "types_searched": ["place", "hotel"],
    "total": 2,
    "results": [
      {
        "id": "place-2930267",
        "type": "place",
        "display_name": "Dubai",
        "subtext": "United Arab Emirates",
        "country_code": "AE",
        "place_id": 2930267,
        "place_type": "region",
        "category": "city",
        "hotel_count": 10983
      },
      {
        "id": "hotel-10001",
        "type": "hotel",
        "display_name": "Example Hotel Dubai",
        "subtext": "5★ · Dubai, AE",
        "country_code": "AE",
        "hotel_id": "10001",
        "stars": 5
      }
    ]
  }
}

Request fields

Field	What it means	How to use it
`q`	The text the guest typed. Required.	Trim it. Send at least 3 characters to get results.
`types`	Comma-separated result types: `place`, `hotel`. Optional.	Omit for both. Send `types=place` for a city/area picker without individual hotels.
`limit`	Number of results, 1 to 20. Default 10.	Places and hotels share this budget.

Response field guide

Field	What it means	How to use it
`data.query`	The query that was searched (trimmed).	Echo only.
`data.types_searched`	Types that were searched.	Echo only.
`data.total`	Number of items in `results`.	Not a count of all catalogue matches.
`data.results[].id`	UI key, such as `place-2930267` or `hotel-10001`.	Use as a list key only. Never send it to search.
`data.results[].type`	`place` or `hotel`.	Decides which ID you send and what the row looks like.
`data.results[].display_name`	Main label.	Show it.
`data.results[].subtext`	Supporting line: location path for places (airports, stations and attractions start with their category), stars and city for hotels.	Show it. Do not parse it.
`data.results[].country_code`	ISO 3166-1 alpha-2 country code.	Use for a flag or grouping.
`data.results[].place_id`	Place ID (number). Only on places.	Send as `destination.id` with `destination.type = "place"`, or as `place_id` to Get Hotel Filters.
`data.results[].hotel_id`	Hotel ID (string). Only on hotels.	Send as `destination.id` (as a number) with `destination.type = "hotel"`.
`data.results[].category`	Guest-facing place category: `country`, `region`, `city`, `area`, `airport`, `station`, `attraction` or `place`.	Pick an icon or label from it.
`data.results[].place_type`	Internal geographic level of a place.	Do not show it and do not branch on it.
`data.results[].hotel_count`	Searchable hotels under the place.	Show as “10,983 hotels”. It is a catalogue count, not availability.
`data.results[].stars`	Star rating of a hotel; `0` means unrated.	Show stars only when above 0.

Use the selection in hotel search

Selected result `type`	Send as `destination.type`	Send as `destination.id`
`place`	`place`	`place_id`
`hotel`	`hotel`	`hotel_id` as a number

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

A place search returns many hotels with paging, filters and sorting. A hotel search returns that one property.

Caching

Cache successful responses for up to 48 hours.
Keep separate cache entries per organization, environment and enabled supplier set. Include the trimmed, lowercased q, types and limit in the key.
Invalidate cached responses when your supplier connections change.
Do not cache errors or empty results from a failed call.

Autocomplete helps a guest choose a destination. It does not promise price, availability or bookability. Those come from search, room availability and prebook.

Common mistakes

Sending id (place-2930267) as the destination ID. Send the number in place_id or hotel_id.
Sending the hotel’s hotel_id string as a string. destination.id is a number.
Calling with 2 characters and treating the empty result as “no destinations”. It only means the query is too short.
Treating an empty result in Sandbox as an authentication or format error. Sandbox only covers the test cities. Try one of those.
Reordering results. The list is balanced across places and hotels on purpose.

Next step

Pass the selection to Search Hotels. To build a filter drawer for a selected place, call Get Hotel Filters. The OpenAPI section below lists every parameter and response field.

Authorizations

x-api-key

string

header

required

Environment-specific API key created in the Unifystays portal

Headers

Query Parameters

string

required

Text typed by the guest (hotel, city, area, airport or landmark name). Minimum 2 characters, but matching starts at 3 characters: a 2-character query is accepted and returns an empty list.

Minimum string length: 2

Example:

"mum"

types

enum<string>[]

Comma-separated result types to include: place, hotel. Omit to return both. Use types=place for a city/area picker that does not suggest individual hotels.

Available options:

hotel,

place

Example:

"place,hotel"

limit

number

default:10

Maximum number of results to return (1-20, default 10). Places and hotels share this budget, so a mixed query returns fewer than 10 of each.

Required range: 1 <= x <= 20

Example:

10

Response

Autocomplete results

success

boolean

required

True when the request succeeded.

Example:

true

message

string

required

Human-readable status. "No destinations found for the given query" when the list is empty. Do not parse.

Example:

"Destinations fetched successfully"

data

object

required

Autocomplete payload.

Show child attributes

Overview

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

Build the picker

Request example

Response example

Request fields

Response field guide

Use the selection in hotel search

Caching

Common mistakes

Next step

Authorizations

Headers

Query Parameters

Response

​Build the picker

​Request example

​Response example

​Request fields

​Response field guide

​Use the selection in hotel search

​Caching

​Common mistakes

​Next step

Authorizations

Headers

Query Parameters

Response

Build the picker

Request example

Response example

Request fields

Response field guide

Use the selection in hotel search

Caching

Common mistakes

Next step