Search Hotel Offers by Number of Nights (Flexible Dates)
flexible_hotels_search_flexible_offersSearch hotel prices for a fixed number of nights across any check-in dates in a window, returning the cheapest offers with booking links.
Instructions
Find the cheapest hotel offers for a fixed NUMBER OF NIGHTS across a WINDOW of possible check-in dates, instead of a single fixed check-in/check-out date pair. This is the core tool of this server.
For example: "3 nights in Tel Aviv, sometime between Sep 1 and Sep 20" is expressed as nights=3, earliest_check_in="2026-09-01", latest_check_in="2026-09-20". The tool scans every possible check-in date in that window (each implying checkout = check-in + nights), fetches real priced offers for each, and returns the cheapest options found, sorted by price — so the caller can see which exact dates are the best deal.
This does NOT search by a single fixed date — for that, just set earliest_check_in = latest_check_in. This is an AFFILIATE search tool: it never collects payment details or creates a booking. Each returned offer includes a bookingUrl — a link to the real hotel/OTA listing where the guest can complete the purchase themselves, if they choose to. Data comes from the Amadeus for Developers hotel API (free test/sandbox environment by default).
Args:
city_code (string): 3-letter IATA city code, e.g. "TLV" (use resolve_city_code to find it from a name)
nights (number): exact stay length in nights, 1-28
earliest_check_in / latest_check_in (YYYY-MM-DD): the flexible window of possible check-in dates, at most 30 days apart
hotel_ids (string[], optional): restrict to specific Amadeus hotelIds (from list_hotels_in_city)
max_hotels (number): if hotel_ids is omitted, how many hotels in the city to auto-check (default 15)
adults (number): guests per room (default 2)
room_quantity (number): rooms to book (default 1)
currency (string, optional): 3-letter ISO currency code, e.g. "USD"
max_results (number): how many offers to return, cheapest first (default 10)
response_format ('markdown' | 'json'): output format (default markdown)
Returns: For JSON format: { "cityCode": string, "nights": number, "earliestCheckIn": string, "latestCheckIn": string, "datesScanned": number, "datesWithOffers": number, "datesSkipped": [{ "date": string, "reason": string }], "hotelsConsidered": number, "offers": [{ "offerId", "hotelId", "hotelName", "checkInDate", "checkOutDate", "nights", "currency", "totalPrice", "boardType", "roomDescription", "bookingUrl" }, ...], "cheapest": <same shape as one offer, or null>, "truncated": boolean }
Examples:
Use when: "find me the cheapest 3-night stay in Paris sometime in the next month"
Use when: "is it cheaper to go for a long weekend early or late September?"
Don't use when: the user already has exact fixed dates in mind — a single-date search is faster (set earliest_check_in = latest_check_in), though this tool still works for that case.
Error Handling:
Returns an error if the date window exceeds 30 days — narrow it and retry
Individual dates that error out (e.g. sandbox has no data) are listed in datesSkipped rather than failing the whole search
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"city_code": "<city_code>",
"nights": "<nights>",
"earliest_check_in": "<earliest_check_in>",
"latest_check_in": "<latest_check_in>"
},
"name": "flexible_hotels_search_flexible_offers"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| adults | No | Number of adult guests per room | |
| nights | Yes | Exact number of consecutive nights the guest wants to stay, e.g. 3 | |
| currency | No | Optional 3-letter ISO currency code to request prices in, e.g. 'USD', 'EUR', 'ILS' | |
| city_code | Yes | IATA city code to search in, e.g. 'TLV' for Tel Aviv (use resolve_city_code to find it from a name) | |
| hotel_ids | No | Optional list of specific Amadeus hotelIds to restrict the search to (from list_hotels_in_city). If omitted, the tool automatically looks up hotels in city_code and checks up to max_hotels of them. | |
| max_hotels | No | When hotel_ids is not provided, how many hotels in the city to check (higher = more thorough but slower, capped at 30) | |
| max_results | No | Maximum number of offers to return, sorted cheapest first | |
| room_quantity | No | Number of rooms to book | |
| latest_check_in | Yes | Latest allowed check-in date, YYYY-MM-DD. Must be no more than 30 days after earliest_check_in. | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable | markdown |
| earliest_check_in | Yes | Earliest allowed check-in date, YYYY-MM-DD. The search scans every possible check-in date from this date through latest_check_in. |