FlightPowers: search hotels
search_hotelsFlightPowers hotel search: live Booking.com availability and nightly prices for a destination and date range. Input: a free-text destination the way a person would say it ("Rome", "Tokyo Shibuya"), plus check-in and check-out dates. Returns each property's price, review score, room type, location, latitude/longitude and a booking link.
Set price_as_seen_from to a two-letter country code to price the same stay the way a shopper resident in that country would see it, which no other travel tool here can do. Gaps are real but usually modest and property-dependent, and rates move between calls, so hold one named property fixed, call each country a few times, and never read one call per country as a gap.
A date range and a nights value price several stays in one call, like the flights tools: pass checkin_date_from, checkin_date_to and nights (a number, or a list like [2, 3, 7]) instead of a fixed checkin_date/checkout_date, and every check-in date is priced separately. The answer is stays -- one entry per stay with its cheapest property, per-night price and median -- plus cheapest_overall, and the full property list for the cheapest stay only. Each stay is one request billed to your plan; max_searches caps it, and a request that expands past the cap is sampled evenly across the range and says so in search_coverage.
Set providers to price the same stay on more than one source in one call: ["booking"] (the default), ["airbnb"], or both. Booking rows rate out of 10 and Airbnb rows out of 5, so read rating_scale on every row before comparing two of them. A source you have no RapidAPI key for is not called and is named in providers_skipped with a subscribe link, never quietly dropped.
Rates go stale within minutes: never reuse an earlier result, search again.
Requires the caller's own RapidAPI key for the Booking Live API. Get one (free tier available) at https://rapidapi.com/mtnrabi/api/booking-live-api, then pass it as an x-rapidapi-key header (preferred), a ?rapidapi_key= query parameter on the server URL, or your client's own API key field -- first non-empty wins. Usage counts against the caller's own RapidAPI plan, not ours; every response reports what it spent and what is left in api_usage. No key? Sign in with Google and the first 10 searches each day are free on this server -- ad-free, nothing to paste. Connect your own RapidAPI key at https://hotels.flightpowers.com/connect to remove the cap.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| adults | No | Number of adult guests. Defaults to the upstream default when omitted. | |
| nights | No | How many nights to stay, as a number (3) or a list ([2, 3, 7]) to price several lengths. Derives the check-out date from each check-in date, so it replaces checkout_date rather than joining it. | |
| filters | No | Property filters to apply, e.g. ["free_cancellation", "breakfast_included"]. An unknown name is rejected with the list of valid ones rather than being ignored. | |
| children | No | Number of children sharing the room. | |
| currency | No | ISO currency code for the prices returned, e.g. "usd". | |
| providers | No | Which sources to price this stay on, e.g. ["booking"], ["airbnb"] or ["booking", "airbnb"]. Defaults to ["booking"]. Each source is a separate RapidAPI subscription, so a source you have no key for is not called; it comes back named in providers_skipped with the reason and where to subscribe, rather than silently missing. filters and price_as_seen_from apply to booking only; airbnb takes price_min, price_max and room_types instead, and rows from it carry rating_scale 5 where booking's carry 10. | |
| destination | Yes | Where to stay, in free text the way a person would say it, e.g. "Rome" or "Tokyo Shibuya". A city, district, landmark or region all work; no internal location ID is needed. | |
| checkin_date | No | First night of the stay, "YYYY-MM-DD". Give this with checkout_date for one stay, or use checkin_date_from plus checkin_date_to for a range of check-in dates. | |
| max_searches | No | The billed requests this call may make, up or down. One stay is one request, so a 30-day range at two lengths is 60 and a month at three is 93 -- the cap rises to cover a request that size by itself. Set it lower to spend less, or higher (hard maximum 200) for a wider grid; either way the range is sampled evenly across the calendar rather than cut short at the front. | |
| checkout_date | No | Departure morning, "YYYY-MM-DD". Must be after checkin_date. Give either this or nights, not both. | |
| checkin_date_to | No | Last check-in date of the range, "YYYY-MM-DD". | |
| budget_per_night | No | Only return properties at or below this nightly price, in `currency`. | |
| checkin_date_from | No | First check-in date of a range, "YYYY-MM-DD". Needs checkin_date_to and nights, and prices one stay per check-in date in the range -- the hotel equivalent of the flights date range. | |
| price_as_seen_from | No | Two-letter country code, e.g. "de". Prices the stay through a residential connection in that country, so the result is what a shopper resident there would be quoted. For a rate-parity check hold one named property fixed and call each country a few times, because rates move between calls and one call per country can show a gap that is not there. Omit it for a neutral price. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| stays | No | One entry per stay the REQUEST asked for, in request order, present whether or not that stay was priced. Only on a date-range search (checkin_date_from / checkin_date_to / nights); a single stay does not carry it. Read this rather than inferring coverage from `results`: `results` holds the full property list for the CHEAPEST stay only, so a stay missing from it looks identical to a stay that had nothing. `reason` says which kind of hole an unpriced stay is: 'no_availability' (searched, answered, nothing came back), 'no_price' (properties came back, none carried a price), 'search_failed' (the search errored, so nothing is known -- not 'no rooms') or 'not_searched' (the per-call fan-out cap sampled it away). Counts are null rather than zero on those last two, because zero reads as 'nothing there' and neither case knows that. | |
| caveats | No | Sentences that must be read before one source is called cheaper than another -- differing rating scales, differing tax treatment, differing currencies, a source that did not answer. | |
| message | No | ||
| partial | No | Present when some stays failed but others were priced. Plain text saying how much of the request the answer covers. | |
| results | Yes | The properties found, already sorted and deduplicated. An empty array is only meaningful when search_status is 'empty'. Each row is the source's own object, passed through. latitude and longitude are the property's WGS84 coordinates in decimal degrees, from the source that answered (Booking.com on Booking rows, Airbnb on Airbnb rows), null when the source publishes none. | |
| api_usage | No | What this call cost the caller's own RapidAPI plan, and what remains on it. Present on every response that reached the upstream, including a degraded one -- a search that failed was still billed. | |
| providers | No | One entry per source that was called, in the order they were requested. Only present when `providers` named more than the default source. | |
| signup_url | No | Where the caller subscribes or changes plan. | |
| result_count | No | ||
| needs_api_key | No | True when no usable RapidAPI key arrived with the call, or the upstream rejected the one that did. No search was run and nothing was billed; signup_url and message say how to fix it. | |
| search_status | No | Date-range searches only, except 'trial_exhausted'. 'ok': every stay searched was priced. 'empty': they all answered and none had priced availability -- a real answer. 'partial': some stays were priced and some errored. 'degraded': every stay errored, so nothing is known; safe to retry. 'trial_exhausted': the free signed-in allowance on this server is spent for today, so nothing was searched and nothing was billed; it renews at 00:00 UTC and connecting your own RapidAPI key removes the cap. Retrying does not help. 'quota_exceeded': the search was refused because the caller's remaining allowance or plan quota cannot cover the number of combinations asked for; combos_requested and combos_allowed_now carry the two numbers. Nothing was searched beyond what it cost to read the quota. Retrying the same search does not help -- ask for fewer dates or nights, or move to a larger plan. | |
| applied_filters | No | Which of the requested filters the upstream actually applied. Untyped: the shape is the upstream's, echoed through. | |
| quota_exhausted | No | True when the caller's RapidAPI plan has no requests left for the current period. | |
| search_coverage | No | What was actually priced on a date-range search. Present whether or not the request was truncated, so a model can state honestly what its answer rests on. | |
| cheapest_overall | No | The cheapest stay across everything priced, or null when nothing was. `results` holds this stay's full property list. | |
| results_for_stay | No | Which stay `results` belongs to on a date-range search, or null when nothing was priced. Without it the rows read as 'the search's results' and get quoted against the wrong dates. | |
| providers_skipped | No | Sources that were NOT called, each named with why and where to subscribe. A source here contributed nothing to results and is counted nowhere. It is listed rather than dropped because a silently missing source is indistinguishable from a source that had nothing. |