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 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 itineraries or properties found, already sorted and deduplicated. An empty array is only meaningful when search_status is 'empty'. | |
| 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. |