FlightPowers: find one hotel by name
find_hotel_by_nameFlightPowers single-property lookup: live Booking.com availability and pricing for one named property. Input: the hotel name a person would type (adding the city helps when a chain has many properties) plus check-in and check-out dates -- no internal property ID needed, the resolution is done for you. Returns the property's price, review score, room type, latitude/longitude and a booking link. Use it to check one specific hotel, or to track a single property's price over time.
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 this property is priced for every check-in date -- a rate calendar for one hotel. The answer is stays, one entry per date with that date's price and per-night rate, plus cheapest_overall. Each stay is one request billed to your plan; max_searches caps it, and a range that expands past the cap is sampled evenly across the calendar and says so in search_coverage.
price_as_seen_from prices the stay as a shopper resident in that country would see it. Gaps are real but usually modest and property-dependent, and rates move between calls, so call each country a few times on this same property before reporting a gap.
Rates go stale within minutes: never reuse an earlier result.
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. | |
| 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. | |
| children | No | Number of children sharing the room. | |
| currency | No | ISO currency code for the prices returned, e.g. "usd". | |
| hotel_name | Yes | The property name a person would type, e.g. "Hotel Artemide". Adding the city ("Hotel Artemide Rome") disambiguates a chain with many properties. No internal property 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 rate calendar. | |
| max_searches | No | The billed requests this call may make, up or down. One stay is one request; the cap rises by itself to cover a month-sized request, and anything past the cap in force 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". | |
| checkin_date_from | No | First check-in date of a range, "YYYY-MM-DD". Needs checkin_date_to and nights, and prices this property on every check-in date in the range -- one call, a rate calendar. | |
| price_as_seen_from | No | Two-letter country code, e.g. "de". Prices the stay as a shopper resident in that country would see it. Call each country a few times on this same property before reporting a gap, because rates move between calls and gaps are usually modest and property-dependent. |
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. |