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
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. |