Search Hotels

curl "$UNIFYSTAYS_BASE_URL/hotels/search" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "destination": {
      "type": "city",
      "id": 101
    },
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ],
    "star_ratings": [4, 5],
    "limit": 20,
    "pricing_mode": "instant",
    "sort": "recommended"
  }'

{
  "success": true,
  "message": "Hotels fetched successfully",
  "data": {
    "search_info": {
      "city_id": 1,
      "city": "Mumbai",
      "country_code": "IN",
      "check_in": "2026-07-01",
      "check_out": "2026-07-04",
      "nights": 3,
      "total_rooms": 2,
      "total_guests": 5,
      "price_sort": "recommended",
      "place_id": 2930267,
      "place": "Bali",
      "place_type": "region"
    },
    "total_results": 42,
    "requested_results": 20,
    "returned_results": 20,
    "hotels": [
      {
        "hotel_id": "123456",
        "hotel_name": "The Taj Mahal Palace",
        "city": "Mumbai",
        "country": "India",
        "facilities": [
          "Free WiFi",
          "Swimming pool",
          "Breakfast"
        ],
        "availability_band": 0,
        "price": {
          "amount": 275000,
          "currency": "USD",
          "rate_type": "live",
          "is_refundable": true,
          "free_cancellation_until": "2026-08-25T23:59:59.000Z"
        },
        "stars": 5,
        "address": "Apollo Bunder, Colaba",
        "latitude": 18.9217,
        "longitude": 72.8332,
        "main_image_url": "https://cdn.example.com/hotels/taj.jpg",
        "chain": "Marriott",
        "distance_from_center_km": 2.1,
        "value_pct": 18,
        "typical_price_usd_cents": 168000,
        "vs_typical_pct": 22
      }
    ],
    "search_id": "srch_a1b2c3d4e5f6g7h8",
    "refresh_status": "PENDING",
    "next_cursor": "1012.4_1283771",
    "similar_hotels": [
      {
        "hotel_id": "123456",
        "hotel_name": "The Taj Mahal Palace",
        "city": "Mumbai",
        "country": "India",
        "facilities": [
          "Free WiFi",
          "Swimming pool",
          "Breakfast"
        ],
        "availability_band": 0,
        "price": {
          "amount": 275000,
          "currency": "USD",
          "rate_type": "live",
          "is_refundable": true,
          "free_cancellation_until": "2026-08-25T23:59:59.000Z"
        },
        "stars": 5,
        "address": "Apollo Bunder, Colaba",
        "latitude": 18.9217,
        "longitude": 72.8332,
        "main_image_url": "https://cdn.example.com/hotels/taj.jpg",
        "chain": "Marriott",
        "distance_from_center_km": 2.1,
        "value_pct": 18,
        "typical_price_usd_cents": 168000,
        "vs_typical_pct": 22,
        "distance_km": 1.2
      }
    ]
  }
}

POST

hotels

curl "$UNIFYSTAYS_BASE_URL/hotels/search" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "destination": {
      "type": "city",
      "id": 101
    },
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ],
    "star_ratings": [4, 5],
    "limit": 20,
    "pricing_mode": "instant",
    "sort": "recommended"
  }'

{
  "success": true,
  "message": "Hotels fetched successfully",
  "data": {
    "search_info": {
      "city_id": 1,
      "city": "Mumbai",
      "country_code": "IN",
      "check_in": "2026-07-01",
      "check_out": "2026-07-04",
      "nights": 3,
      "total_rooms": 2,
      "total_guests": 5,
      "price_sort": "recommended",
      "place_id": 2930267,
      "place": "Bali",
      "place_type": "region"
    },
    "total_results": 42,
    "requested_results": 20,
    "returned_results": 20,
    "hotels": [
      {
        "hotel_id": "123456",
        "hotel_name": "The Taj Mahal Palace",
        "city": "Mumbai",
        "country": "India",
        "facilities": [
          "Free WiFi",
          "Swimming pool",
          "Breakfast"
        ],
        "availability_band": 0,
        "price": {
          "amount": 275000,
          "currency": "USD",
          "rate_type": "live",
          "is_refundable": true,
          "free_cancellation_until": "2026-08-25T23:59:59.000Z"
        },
        "stars": 5,
        "address": "Apollo Bunder, Colaba",
        "latitude": 18.9217,
        "longitude": 72.8332,
        "main_image_url": "https://cdn.example.com/hotels/taj.jpg",
        "chain": "Marriott",
        "distance_from_center_km": 2.1,
        "value_pct": 18,
        "typical_price_usd_cents": 168000,
        "vs_typical_pct": 22
      }
    ],
    "search_id": "srch_a1b2c3d4e5f6g7h8",
    "refresh_status": "PENDING",
    "next_cursor": "1012.4_1283771",
    "similar_hotels": [
      {
        "hotel_id": "123456",
        "hotel_name": "The Taj Mahal Palace",
        "city": "Mumbai",
        "country": "India",
        "facilities": [
          "Free WiFi",
          "Swimming pool",
          "Breakfast"
        ],
        "availability_band": 0,
        "price": {
          "amount": 275000,
          "currency": "USD",
          "rate_type": "live",
          "is_refundable": true,
          "free_cancellation_until": "2026-08-25T23:59:59.000Z"
        },
        "stars": 5,
        "address": "Apollo Bunder, Colaba",
        "latitude": 18.9217,
        "longitude": 72.8332,
        "main_image_url": "https://cdn.example.com/hotels/taj.jpg",
        "chain": "Marriott",
        "distance_from_center_km": 2.1,
        "value_pct": 18,
        "typical_price_usd_cents": 168000,
        "vs_typical_pct": 22,
        "distance_km": 1.2
      }
    ]
  }
}

Hotel search is the shopping entry point for your enabled suppliers. Start with a destination returned by Destination Autocomplete and use the guest nationality iso_code returned by Nationalities.

Request Example

curl "$UNIFYSTAYS_BASE_URL/hotels/search" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "destination": {
      "type": "city",
      "id": 101
    },
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ],
    "star_ratings": [4, 5],
    "limit": 20,
    "pricing_mode": "instant",
    "sort": "recommended"
  }'

Destination and Guest Inputs

Input	Source	Integration rule
`destination.type` and `destination.id`	Destination autocomplete	Keep the selected type and send its matching city, hotel, or place ID.
`nationality`	Nationalities	Send the selected ISO alpha-2 `iso_code`.
`rooms`	Your guest form	Send each room’s adults and child ages; keep the same occupancy for room options.
Stay dates	Your guest form	Send dates in `YYYY-MM-DD` format.

Pricing Modes

Mode	Behavior	Recommended use
`instant`	Returns cached or estimated prices quickly, then refreshes supplier prices in the background.	Customer-facing result pages.
`live`	Waits up to roughly 15 seconds for supplier refresh in the search response.	Low-volume or machine-to-machine rate shopping.

When using instant, retain data.search_id and poll Get Search Price Updates every two seconds while results are visible.

Pagination and Rendering

Use data.next_cursor as cursor in the next request. Keep the original search inputs when paging.
Use the requested sort consistently across cursor pages.
Merge live updates by hotel_id and re-sort when price changes arrive.
Render similar_hotels as a separate nearby-properties section rather than mixing it into the main result list.
Use fields only when a smaller payload is intentional; hotel_id remains available for merging and selection.

Search prices are shopping data, not a booking confirmation. Request fresh room options for the chosen hotel and prebook immediately before booking.

The OpenAPI section below documents every search filter, occupancy constraint, sort option, response field, and error response.

Authorizations

x-api-key

string

header

required

Environment-specific API key created in the Unifystays portal

Headers

Body

application/json

destination

object

required

Selected destination from the autocomplete widget. Supply the type and id exactly as returned by GET /destinations/autocomplete.

Show child attributes

check_in

string

required

Check-in date in YYYY-MM-DD format. Must be today or a future date.

Example:

"2026-07-01"

check_out

string

required

Check-out date in YYYY-MM-DD format. Must be after check_in.

Example:

"2026-07-04"

rooms

object[]

required

Room configurations. Minimum 1 room, maximum 5 rooms. Each room supports up to 5 total occupants (adults + children).

Required array length: 1 - 5 elements

Show child attributes

star_ratings

array[]

Filter results by star ratings. Pass one or more values from 1–5.

Example:

[4, 5]

price_min_usd_cents

number

Minimum TOTAL price filter in USD cents (across all nights/rooms). Server converts to nightly unit range using computed stay multiplier.

Required range: x >= 0

Example:

5000

price_max_usd_cents

number

Maximum TOTAL price filter in USD cents.

Required range: x >= 1

Example:

500000

property_types

array[]

Filter by property type. Values come from GET /hotels/filters → property_types.

Example:

["Hotel", "Resort"]

chain_ids

array[]

Filter by hotel chain IDs. Values come from GET /hotels/filters → chains.

Example:

[42, 99]

facility_ids

array[]

Filter by facility IDs (matches hotels.facilities[].facility_id). Multiple ids are ANDed — hotel must have all selected facilities. Values come from GET /hotels/filters → facilities.

Example:

[107, 25]

hotel_name

string

Free-text hotel name filter. Server runs ILIKE "%name%".

Example:

"marriott"

hotel_ids

array[]

Filter by specific hotel IDs. Useful when user wants to narrow the result set to one or more particular hotels (e.g. after picking from autocomplete). Matches hotels.hotel_id.

Example:

[1892345, 2031122]

nationality

string

default:IN

Nationality of the guest in ISO alpha-2 format (e.g. IN for Indian, US for United States).

Example:

"IN"

limit

number

default:20

Requested hotels per page. If omitted, default page size is used.

Required range: 1 <= x <= 100

Example:

20

cursor

string

Cursor token for next-page fetch in format "sortKey_hotelId". Pass the next_cursor returned in previous response.

Example:

"1037.5_1892345"

price_sort

enum<string>

default:recommended

Price sort direction for listing page. Uses precomputed sort_price_usd_cents for stable cursor pagination. If omitted, API uses recommended ranking (tier/cache/reliability first).

Available options:

low_to_high,

high_to_low

Example:

"low_to_high"

pricing_mode

enum<string>

default:instant

'instant' (default): returns cached/estimated prices immediately; poll GET /hotels/search/:searchId/prices for live supplier prices. 'live': the request waits (up to ~15s) for the live supplier refresh and returns fresh prices in this single call — one-call integration for machine-to-machine rate shopping.

Available options:

instant,

live

Example:

"instant"

sort

enum<string>

default:recommended

Sort order. Supersedes price_sort when both are sent. recommended (default) = neutral relevance ranking; price_low_to_high / price_high_to_low = by total price; stars = star rating high→low; distance_from_center = closest to the city centre first; value = best value_pct deals first.

Available options:

recommended,

price_low_to_high,

price_high_to_low,

stars,

distance_from_center,

value

Example:

"distance_from_center"

fields

string[]

Sparse fieldset: return only these hotel-item fields (hotel_id is always included). Unknown names are ignored. Trims payloads for mobile / high-volume callers. Example: ["hotel_name","price","stars"].

Example:

["hotel_name", "price", "stars"]

Response

success

boolean

required

Example:

true

message

string

required

Example:

"Hotels fetched successfully"

data

object

required

Show child attributes

⌘I

Overview

Destination & master data

Search & hotels

Bookings

Request Example

Destination and Guest Inputs

Pricing Modes

Authorizations

Headers

Body

Response

​Request Example

​Destination and Guest Inputs

​Pricing Modes

​Pagination and Rendering

Authorizations

Headers

Body

Response

Request Example

Destination and Guest Inputs

Pricing Modes

Pagination and Rendering