search_hotels_availability

Returns a price calendar across a date range — for each check-in date in the window, the cheapest rate among the hotels Vio selected for the search. Use this to answer "when should I go?" questions where the user is flexible on dates.

This is a date-axis tool. For fixed-date hotel search, use search_hotels. For "is this hotel a good deal?" questions, use search_hotels with include: ["analytic"].

Parameters

Search input (provide exactly one)

Parameter	Type	Description
queries	string[] (1-3)	Location or hotel name (e.g., ["Amsterdam"])
latitude + longitude	number	Coordinate-based search
nearMe	boolean	User's current location (requires GPS or geo headers)
address	string	Geocoded address
hotelIds	string[]	Specific hotels (skips internal search)

Date range

Parameter	Type	Description
startDate	string (YYYY-MM-DD)	First check-in date in the calendar. Defaults to today + 15 days.
endDate	string (YYYY-MM-DD)	Last check-in date. Defaults to startDate + 14. Maximum range: 91 days from startDate.
nights	number	Stay length per check-in (default: 3). The calendar shows the cheapest rate for this duration at each check-in date.

Other parameters

Parameter	Type	Description
roomsConfiguration	object[]	Room occupancy (default [{adults: 2}]). Same shape as other tools.
maxHotels	number	Hotels to include in the calendar (default 5, max 5).
searchMode	"fast" | "deep"	fast (default, ~5s soft deadline) or deep (~22s, more thorough). Identical semantics to search_hotels.
sortField	string	Hotel ranking: popularity (default), price, guestRating, starRating, distance. For "cheapest possible trip" intent, pass price — by default the calendar reflects popularity-ranked hotels which can overstate prices vs the actual price floor.
sortOrder	"ascending" | "descending"	Used with sortField.
filters	object	Same hotel-level filters as search_hotels (star rating, guest rating, facilities, themes, price range, property types). See Filters.
currency	string	ISO 4217 (e.g., EUR, USD). Auto-detected from locale if omitted.
priceMode	"total" | "nightly"	total (default) or per-night.
dryRun	boolean	Validate inputs and return the normalized stay metadata without calling the upstream service.

Hotel selection

When hotelIds is provided, those hotels are used directly. Otherwise the tool first runs an offers-aware search to find candidates that have offers for the requested dates and rooms — mirroring the pattern Vio's website uses for its own price-color calendar (search → calendar). Without this step the calendar can surface popular but unbookable hotels.

Use cases

Cheapest dates in a city

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_hotels_availability",
    "arguments": {
      "queries": ["Barcelona"],
      "startDate": "2026-06-01",
      "endDate": "2026-06-30",
      "nights": 3,
      "roomsConfiguration": [{"adults": 2}]
    }
  }
}

Cheapest possible trip — bias toward the price floor

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_hotels_availability",
    "arguments": {
      "queries": ["Lisbon"],
      "startDate": "2026-06-01",
      "endDate": "2026-06-30",
      "nights": 3,
      "sortField": "price",
      "sortOrder": "ascending",
      "filters": {"guestRating": [7, 8, 9, 10]}
    }
  }
}

Date trends for a specific hotel

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_hotels_availability",
    "arguments": {
      "hotelIds": ["hotel_abc123"],
      "startDate": "2026-06-01",
      "endDate": "2026-07-01",
      "nights": 3
    }
  }
}

Coordinate-based, near user

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "search_hotels_availability",
    "arguments": {
      "nearMe": true,
      "startDate": "2026-06-01",
      "endDate": "2026-06-21",
      "nights": 2
    }
  }
}

Response

{
  "language": "en",
  "currency": "EUR",
  "startDate": "2026-06-01",
  "endDate": "2026-06-30",
  "nights": 3,
  "roomConfiguration": [{"adults": 2}],
  "priceScope": "all_rooms_combined",
  "priceLogic": "base_tax_fees",
  "availability": [
    {
      "hotelId": "hotel_abc123",
      "checkIn": "2026-06-01",
      "cheapestRate": {
        "base": 280.0,
        "taxes": 28.5,
        "hotelFees": 12.0,
        "displayPrice": 320.5
      },
      "offerCount": 7
    }
  ]
}

The response is a flat array of (hotelId, checkIn) entries — one per (hotel, date) pair the tool was able to compute a rate for. To get hotel names, locations, and images, call get_hotels with the hotelId values from the calendar.

See Availability entry in Data Types for the full schema.

Notes

• Range cap: 91 days. Longer ranges return a recoverable error.
• Polling: the tool runs a soft-deadline polling loop (5s fast / 22s deep) and returns whatever rates have arrived by then. The response always includes a flat calendar even if some providers were still responding when the deadline hit — no thrown errors on partial completion.
• Hotel diversity: the calendar covers whatever hotels the search step surfaced. To compare a specific shortlist, pass hotelIds directly.