Booking.com Hotel Search (Live Prices)

{'type': 'object', 'required': ['destination', 'checkin_date', 'checkout_date'], 'properties': {'adults': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Number of adult guests. Defaults to the upstream default when omitted.'}, 'children': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Number of children sharing the room.'}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'ISO currency code for every row, e.g. "usd". Sources are asked for the same currency so the totals are comparable; a row that came back in a different one says so in its own currency field and is not converted.'}, 'providers': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}], 'default': None, 'description': 'Which sources to price, e.g. ["booking", "airbnb"]. Defaults to both. A source you have no RapidAPI key for is not called and appears in providers_skipped.'}, 'destination': {'type': 'string', 'description': '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': {'type': 'string', 'description': 'First night of the stay, "YYYY-MM-DD".'}, 'checkout_date': {'type': 'string', 'description': 'Departure morning, "YYYY-MM-DD". Must be after checkin_date.'}}, 'additionalProperties': False}

{'type': 'object', 'title': 'Cross-source hotel rate comparison', 'required': ['providers'], 'properties': {'adults': {'anyOf': [{'type': 'integer'}, {'type': 'null'}]}, 'nights': {'anyOf': [{'type': 'integer', 'minimum': 1}, {'type': 'null'}], 'description': 'Nights between the two dates, or null when the dates could not be read as dates.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': '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': {'type': 'string'}, 'children': {'anyOf': [{'type': 'integer'}, {'type': 'null'}]}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The currency every source was ASKED for.'}, 'api_usage': {'type': 'object', 'properties': {'note': {'type': 'string', 'description': 'The same figures as a sentence, for the model to relay.'}, 'hub_requests_billed': {'type': 'integer', 'minimum': 0, 'description': 'How many HTTP requests RapidAPI actually billed. Larger than requests_used_by_this_call when a search failed with a server error and was retried, because the retry is billed too. This is the figure the invoice will show.'}, 'plan_requests_limit': {'type': 'integer'}, 'plan_requests_remaining': {'type': 'integer'}, 'requests_used_by_this_call': {'type': 'integer', 'minimum': 0, 'description': 'How many date/destination combinations were searched -- what the answer COVERS.'}}, 'description': "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.", 'additionalProperties': True}, 'providers': {'type': 'array', 'items': {'type': 'object', 'required': ['provider', 'search_status'], 'properties': {'top': {'type': 'array', 'items': {'type': 'object', 'additionalProperties': True}, 'description': 'The cheapest few priced rows from this source.'}, 'count': {'anyOf': [{'type': 'integer', 'minimum': 0}, {'type': 'null'}], 'description': "How many properties from this source carried a price. Null when the source did not answer -- zero would read as 'nothing there', which a failed search does not know."}, 'detail': {'type': 'string', 'description': 'Plain text for the model to relay to a human.'}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The currency THIS row's totals are in. Rows in different currencies are not comparable and nothing is converted."}, 'provider': {'type': 'string', 'description': "Which source this row is about, e.g. 'booking'."}, 'median_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'rating_scale': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'description': 'What a review score from this source is out of: 10 on Booking, 5 on Airbnb. Read it before comparing two scores.'}, 'retrieved_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'When these rows were read, taken from the rows themselves rather than from when this answer was assembled.'}, 'cheapest_link': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'cheapest_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'search_reason': {'type': 'string'}, 'search_status': {'enum': ['ok', 'empty', 'degraded', 'skipped'], 'type': 'string', 'description': "'ok': the source answered with priced results. 'empty': it answered and had nothing for that stay -- a real answer. 'degraded': it was asked and could not answer, so count is null and an empty list from it means nothing."}, 'cheapest_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'taxes_included': {'anyOf': [{'type': 'boolean'}, {'type': 'null'}], 'description': "Whether this source's totals include tax. Null means it has not been established for that source, not that tax is excluded."}}, 'description': "What one accommodation source answered. Present for every source that was CALLED, whether or not it answered: a source with search_status 'degraded' carries a reason, a null count and no prices, which is not the same answer as a source that found nothing.", 'additionalProperties': True}}, 'signup_url': {'type': 'string', 'description': 'Where the caller subscribes or changes plan.'}, 'destination': {'type': 'string'}, 'checkin_date': {'type': 'string'}, 'checkout_date': {'type': 'string'}, 'needs_api_key': {'type': 'boolean', 'description': '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.'}, 'quota_exhausted': {'type': 'boolean', 'description': "True when the caller's RapidAPI plan has no requests left for the current period."}, 'providers_skipped': {'type': 'array', 'items': {'type': 'object', 'required': ['provider', 'reason'], 'properties': {'detail': {'type': 'string'}, 'reason': {'type': 'string', 'description': "'no_key': no RapidAPI key for that source's listing arrived with the call. 'not_subscribed': the key supplied is not subscribed to that listing. 'key_rejected': the key was refused outright."}, 'provider': {'type': 'string'}, 'subscribe_url': {'type': 'string'}}, 'additionalProperties': True}, 'description': '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.'}}, 'description': "One stay priced on every source the caller has a key for, one row per source. Read `caveats` and each row's `search_status`, `rating_scale` and `currency` before saying one source is cheaper than another: a degraded source has no count and no prices, and a skipped source is counted nowhere.", 'additionalProperties': True}

{'type': 'object', 'required': ['hotel_name'], 'properties': {'adults': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Number of adult guests.'}, 'nights': {'anyOf': [{'type': 'integer'}, {'type': 'array', 'items': {'type': 'integer'}}, {'type': 'null'}], 'default': None, 'description': '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': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Number of children sharing the room.'}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'ISO currency code for the prices returned, e.g. "usd".'}, 'hotel_name': {'type': 'string', 'description': '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': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': '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': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': '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': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Departure morning, "YYYY-MM-DD". Must be after checkin_date. Give either this or nights, not both.'}, 'checkin_date_to': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Last check-in date of the range, "YYYY-MM-DD".'}, 'checkin_date_from': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': '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': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': '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.'}}, 'additionalProperties': False}

{'type': 'object', 'title': 'Hotel search result', 'required': ['results'], 'properties': {'stays': {'type': 'array', 'items': {'type': 'object', 'required': ['checkin_date', 'checkout_date', 'search_status', 'reason'], 'properties': {'nights': {'anyOf': [{'type': 'integer'}, {'type': 'null'}]}, 'reason': {'enum': ['ok', 'no_availability', 'no_price', 'search_failed', 'not_searched'], 'type': 'string'}, 'cheapest': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'description': 'The cheapest priced property for this stay, or null when it has none. The same row the upstream returned, minus its image URL: on a measured search 73% of the payload was URLs, and an image CDN link is the half no model can open. The booking link is kept.'}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'checkin_date': {'type': 'string'}, 'median_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': "Median stay total over this stay's priced properties -- what the date costs generally, next to what its one cheapest room costs."}, 'priced_count': {'anyOf': [{'type': 'integer', 'minimum': 0}, {'type': 'null'}], 'description': 'How many of those carried a price. The others are not evidence about what the stay costs.'}, 'checkout_date': {'type': 'string'}, 'search_status': {'enum': ['ok', 'empty', 'degraded', 'not_searched'], 'type': 'string'}, 'cheapest_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'property_count': {'anyOf': [{'type': 'integer', 'minimum': 0}, {'type': 'null'}], 'description': 'Properties returned for this stay. Null when it was not searched or its search errored.'}, 'price_per_night': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'cheapest_total divided by nights, rounded.'}}, 'additionalProperties': True}, 'description': "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.\n\nRead 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': {'type': 'array', 'items': {'type': 'string'}, 'description': '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': {'type': 'string'}, 'partial': {'type': 'string', 'description': 'Present when some stays failed but others were priced. Plain text saying how much of the request the answer covers.'}, 'results': {'type': 'array', 'items': {'type': 'object', 'additionalProperties': True}, 'description': "The itineraries or properties found, already sorted and deduplicated. An empty array is only meaningful when search_status is 'empty'."}, 'api_usage': {'type': 'object', 'properties': {'note': {'type': 'string', 'description': 'The same figures as a sentence, for the model to relay.'}, 'hub_requests_billed': {'type': 'integer', 'minimum': 0, 'description': 'How many HTTP requests RapidAPI actually billed. Larger than requests_used_by_this_call when a search failed with a server error and was retried, because the retry is billed too. This is the figure the invoice will show.'}, 'plan_requests_limit': {'type': 'integer'}, 'plan_requests_remaining': {'type': 'integer'}, 'requests_used_by_this_call': {'type': 'integer', 'minimum': 0, 'description': 'How many date/destination combinations were searched -- what the answer COVERS.'}}, 'description': "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.", 'additionalProperties': True}, 'providers': {'type': 'array', 'items': {'type': 'object', 'required': ['provider', 'search_status'], 'properties': {'top': {'type': 'array', 'items': {'type': 'object', 'additionalProperties': True}, 'description': 'The cheapest few priced rows from this source.'}, 'count': {'anyOf': [{'type': 'integer', 'minimum': 0}, {'type': 'null'}], 'description': "How many properties from this source carried a price. Null when the source did not answer -- zero would read as 'nothing there', which a failed search does not know."}, 'detail': {'type': 'string', 'description': 'Plain text for the model to relay to a human.'}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The currency THIS row's totals are in. Rows in different currencies are not comparable and nothing is converted."}, 'provider': {'type': 'string', 'description': "Which source this row is about, e.g. 'booking'."}, 'median_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'rating_scale': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'description': 'What a review score from this source is out of: 10 on Booking, 5 on Airbnb. Read it before comparing two scores.'}, 'retrieved_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'When these rows were read, taken from the rows themselves rather than from when this answer was assembled.'}, 'cheapest_link': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'cheapest_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'search_reason': {'type': 'string'}, 'search_status': {'enum': ['ok', 'empty', 'degraded', 'skipped'], 'type': 'string', 'description': "'ok': the source answered with priced results. 'empty': it answered and had nothing for that stay -- a real answer. 'degraded': it was asked and could not answer, so count is null and an empty list from it means nothing."}, 'cheapest_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'taxes_included': {'anyOf': [{'type': 'boolean'}, {'type': 'null'}], 'description': "Whether this source's totals include tax. Null means it has not been established for that source, not that tax is excluded."}}, 'description': "What one accommodation source answered. Present for every source that was CALLED, whether or not it answered: a source with search_status 'degraded' carries a reason, a null count and no prices, which is not the same answer as a source that found nothing.", 'additionalProperties': True}, 'description': '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': {'type': 'string', 'description': 'Where the caller subscribes or changes plan.'}, 'result_count': {'type': 'integer', 'minimum': 0}, 'needs_api_key': {'type': 'boolean', 'description': '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': {'enum': ['ok', 'empty', 'partial', 'degraded', 'trial_exhausted', 'quota_exceeded'], 'type': 'string', 'description': "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': {'description': "Which of the requested filters the upstream actually applied. Untyped: the shape is the upstream's, echoed through."}, 'quota_exhausted': {'type': 'boolean', 'description': "True when the caller's RapidAPI plan has no requests left for the current period."}, 'search_coverage': {'type': 'object', 'properties': {'note': {'type': 'string'}, 'truncated': {'type': 'boolean', 'description': "True when the request expanded past this call's spend ceiling and was sampled. A stay absent from stays_searched was never priced, which is not the same as having no rooms."}, 'stopped_early': {'type': 'string', 'description': "Present when something other than the cap ended the fan-out. 'deadline': the call reached its time limit and the remaining combinations were never sent or billed, so the results are real but do not cover the whole range."}, 'stays_searched': {'type': 'array', 'items': {'type': 'object', 'properties': {'checkin_date': {'type': 'string'}, 'checkout_date': {'type': 'string'}}, 'additionalProperties': True}, 'description': 'The exact date pairs priced.'}, 'searched_combinations': {'type': 'integer', 'minimum': 0}, 'checkin_dates_searched': {'type': 'array', 'items': {'type': 'string'}}, 'requested_combinations': {'type': 'integer', 'minimum': 0}, 'max_searches_per_request': {'type': 'integer', 'minimum': 1}}, 'description': '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.', 'additionalProperties': True}, 'cheapest_overall': {'anyOf': [{'type': 'object', 'properties': {'total': {'type': 'number'}, 'nights': {'anyOf': [{'type': 'integer'}, {'type': 'null'}]}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'property': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'description': 'The cheapest priced property for this stay, or null when it has none. The same row the upstream returned, minus its image URL: on a measured search 73% of the payload was URLs, and an image CDN link is the half no model can open. The booking link is kept.'}, 'checkin_date': {'type': 'string'}, 'checkout_date': {'type': 'string'}, 'price_per_night': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': True}, {'type': 'null'}], 'description': "The cheapest stay across everything priced, or null when nothing was. `results` holds this stay's full property list."}, 'results_for_stay': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'description': "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': {'type': 'array', 'items': {'type': 'object', 'required': ['provider', 'reason'], 'properties': {'detail': {'type': 'string'}, 'reason': {'type': 'string', 'description': "'no_key': no RapidAPI key for that source's listing arrived with the call. 'not_subscribed': the key supplied is not subscribed to that listing. 'key_rejected': the key was refused outright."}, 'provider': {'type': 'string'}, 'subscribe_url': {'type': 'string'}}, 'additionalProperties': True}, 'description': '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.'}}, 'description': "A completed hotel search. A single stay carries no search_status: the hotels upstream reports no search-status header, and one call either answered or raised. A DATE-RANGE search does carry one, derived from the fan-out rather than from the upstream -- some of its stays can fail while others answer, and `results` then holds only the cheapest stay's properties, so `stays` is where the shape of the answer lives.", 'additionalProperties': True}

{'type': 'object', 'required': ['destination'], 'properties': {'adults': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Number of adult guests. Defaults to the upstream default when omitted.'}, 'nights': {'anyOf': [{'type': 'integer'}, {'type': 'array', 'items': {'type': 'integer'}}, {'type': 'null'}], 'default': None, 'description': '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': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}], 'default': None, 'description': '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': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Number of children sharing the room.'}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'ISO currency code for the prices returned, e.g. "usd".'}, 'providers': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}], 'default': None, 'description': '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': {'type': 'string', 'description': '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': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': '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': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': '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': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Departure morning, "YYYY-MM-DD". Must be after checkin_date. Give either this or nights, not both.'}, 'checkin_date_to': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Last check-in date of the range, "YYYY-MM-DD".'}, 'budget_per_night': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Only return properties at or below this nightly price, in `currency`.'}, 'checkin_date_from': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': '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': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': '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.'}}, 'additionalProperties': False}

{'type': 'object', 'title': 'Hotel search result', 'required': ['results'], 'properties': {'stays': {'type': 'array', 'items': {'type': 'object', 'required': ['checkin_date', 'checkout_date', 'search_status', 'reason'], 'properties': {'nights': {'anyOf': [{'type': 'integer'}, {'type': 'null'}]}, 'reason': {'enum': ['ok', 'no_availability', 'no_price', 'search_failed', 'not_searched'], 'type': 'string'}, 'cheapest': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'description': 'The cheapest priced property for this stay, or null when it has none. The same row the upstream returned, minus its image URL: on a measured search 73% of the payload was URLs, and an image CDN link is the half no model can open. The booking link is kept.'}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'checkin_date': {'type': 'string'}, 'median_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': "Median stay total over this stay's priced properties -- what the date costs generally, next to what its one cheapest room costs."}, 'priced_count': {'anyOf': [{'type': 'integer', 'minimum': 0}, {'type': 'null'}], 'description': 'How many of those carried a price. The others are not evidence about what the stay costs.'}, 'checkout_date': {'type': 'string'}, 'search_status': {'enum': ['ok', 'empty', 'degraded', 'not_searched'], 'type': 'string'}, 'cheapest_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'property_count': {'anyOf': [{'type': 'integer', 'minimum': 0}, {'type': 'null'}], 'description': 'Properties returned for this stay. Null when it was not searched or its search errored.'}, 'price_per_night': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'cheapest_total divided by nights, rounded.'}}, 'additionalProperties': True}, 'description': "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.\n\nRead 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': {'type': 'array', 'items': {'type': 'string'}, 'description': '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': {'type': 'string'}, 'partial': {'type': 'string', 'description': 'Present when some stays failed but others were priced. Plain text saying how much of the request the answer covers.'}, 'results': {'type': 'array', 'items': {'type': 'object', 'additionalProperties': True}, 'description': "The itineraries or properties found, already sorted and deduplicated. An empty array is only meaningful when search_status is 'empty'."}, 'api_usage': {'type': 'object', 'properties': {'note': {'type': 'string', 'description': 'The same figures as a sentence, for the model to relay.'}, 'hub_requests_billed': {'type': 'integer', 'minimum': 0, 'description': 'How many HTTP requests RapidAPI actually billed. Larger than requests_used_by_this_call when a search failed with a server error and was retried, because the retry is billed too. This is the figure the invoice will show.'}, 'plan_requests_limit': {'type': 'integer'}, 'plan_requests_remaining': {'type': 'integer'}, 'requests_used_by_this_call': {'type': 'integer', 'minimum': 0, 'description': 'How many date/destination combinations were searched -- what the answer COVERS.'}}, 'description': "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.", 'additionalProperties': True}, 'providers': {'type': 'array', 'items': {'type': 'object', 'required': ['provider', 'search_status'], 'properties': {'top': {'type': 'array', 'items': {'type': 'object', 'additionalProperties': True}, 'description': 'The cheapest few priced rows from this source.'}, 'count': {'anyOf': [{'type': 'integer', 'minimum': 0}, {'type': 'null'}], 'description': "How many properties from this source carried a price. Null when the source did not answer -- zero would read as 'nothing there', which a failed search does not know."}, 'detail': {'type': 'string', 'description': 'Plain text for the model to relay to a human.'}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The currency THIS row's totals are in. Rows in different currencies are not comparable and nothing is converted."}, 'provider': {'type': 'string', 'description': "Which source this row is about, e.g. 'booking'."}, 'median_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'rating_scale': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'description': 'What a review score from this source is out of: 10 on Booking, 5 on Airbnb. Read it before comparing two scores.'}, 'retrieved_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'When these rows were read, taken from the rows themselves rather than from when this answer was assembled.'}, 'cheapest_link': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'cheapest_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'search_reason': {'type': 'string'}, 'search_status': {'enum': ['ok', 'empty', 'degraded', 'skipped'], 'type': 'string', 'description': "'ok': the source answered with priced results. 'empty': it answered and had nothing for that stay -- a real answer. 'degraded': it was asked and could not answer, so count is null and an empty list from it means nothing."}, 'cheapest_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'taxes_included': {'anyOf': [{'type': 'boolean'}, {'type': 'null'}], 'description': "Whether this source's totals include tax. Null means it has not been established for that source, not that tax is excluded."}}, 'description': "What one accommodation source answered. Present for every source that was CALLED, whether or not it answered: a source with search_status 'degraded' carries a reason, a null count and no prices, which is not the same answer as a source that found nothing.", 'additionalProperties': True}, 'description': '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': {'type': 'string', 'description': 'Where the caller subscribes or changes plan.'}, 'result_count': {'type': 'integer', 'minimum': 0}, 'needs_api_key': {'type': 'boolean', 'description': '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': {'enum': ['ok', 'empty', 'partial', 'degraded', 'trial_exhausted', 'quota_exceeded'], 'type': 'string', 'description': "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': {'description': "Which of the requested filters the upstream actually applied. Untyped: the shape is the upstream's, echoed through."}, 'quota_exhausted': {'type': 'boolean', 'description': "True when the caller's RapidAPI plan has no requests left for the current period."}, 'search_coverage': {'type': 'object', 'properties': {'note': {'type': 'string'}, 'truncated': {'type': 'boolean', 'description': "True when the request expanded past this call's spend ceiling and was sampled. A stay absent from stays_searched was never priced, which is not the same as having no rooms."}, 'stopped_early': {'type': 'string', 'description': "Present when something other than the cap ended the fan-out. 'deadline': the call reached its time limit and the remaining combinations were never sent or billed, so the results are real but do not cover the whole range."}, 'stays_searched': {'type': 'array', 'items': {'type': 'object', 'properties': {'checkin_date': {'type': 'string'}, 'checkout_date': {'type': 'string'}}, 'additionalProperties': True}, 'description': 'The exact date pairs priced.'}, 'searched_combinations': {'type': 'integer', 'minimum': 0}, 'checkin_dates_searched': {'type': 'array', 'items': {'type': 'string'}}, 'requested_combinations': {'type': 'integer', 'minimum': 0}, 'max_searches_per_request': {'type': 'integer', 'minimum': 1}}, 'description': '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.', 'additionalProperties': True}, 'cheapest_overall': {'anyOf': [{'type': 'object', 'properties': {'total': {'type': 'number'}, 'nights': {'anyOf': [{'type': 'integer'}, {'type': 'null'}]}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'property': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'description': 'The cheapest priced property for this stay, or null when it has none. The same row the upstream returned, minus its image URL: on a measured search 73% of the payload was URLs, and an image CDN link is the half no model can open. The booking link is kept.'}, 'checkin_date': {'type': 'string'}, 'checkout_date': {'type': 'string'}, 'price_per_night': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': True}, {'type': 'null'}], 'description': "The cheapest stay across everything priced, or null when nothing was. `results` holds this stay's full property list."}, 'results_for_stay': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'description': "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': {'type': 'array', 'items': {'type': 'object', 'required': ['provider', 'reason'], 'properties': {'detail': {'type': 'string'}, 'reason': {'type': 'string', 'description': "'no_key': no RapidAPI key for that source's listing arrived with the call. 'not_subscribed': the key supplied is not subscribed to that listing. 'key_rejected': the key was refused outright."}, 'provider': {'type': 'string'}, 'subscribe_url': {'type': 'string'}}, 'additionalProperties': True}, 'description': '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.'}}, 'description': "A completed hotel search. A single stay carries no search_status: the hotels upstream reports no search-status header, and one call either answered or raised. A DATE-RANGE search does carry one, derived from the fan-out rather than from the upstream -- some of its stays can fail while others answer, and `results` then holds only the cheapest stay's properties, so `stays` is where the shape of the answer lives.", 'additionalProperties': True}