MCP + API · kestrel/booking-prices-scraper
Booking.com Scraper — Hotel Prices & Availability by Date
Booking.com prices and availability by date for destinations or hotels by URL, name or id. One row per hotel: stay total, nightly rate, taxes, free cancellation, breakfast, stars, review score, sold out. Optional room rates. Filters before billing: max price, star class. Price tracking, comp sets.
Open Actor Download MCP config
Connect this tool
Add this URL as a remote MCP server in your client, then sign in to Apify. For a client-specific setup, use Apify's configurator.
https://mcp.apify.com?tools=call-actor,fetch-actor-details,kestrel/booking-prices-scraper
Generic MCP client configuration
{
"mcpServers": {
"kestrel-booking-prices-scraper": {
"url": "https://mcp.apify.com?tools=call-actor,fetch-actor-details,kestrel/booking-prices-scraper"
}
}
}
Understand the output before you run
One row per property with its price for the stay, optional room-rate rows, and one status row per target.
Declared dataset fields and row types · Output locations and dataset links
Use the declared dataset schema for item fields; the output schema describes where results are stored. Optional fields may be null or absent. If an integration shows a sampled schema without an optional field, check this declaration, the Actor instructions and actual returned rows before concluding that the field is unsupported.
Inspect 76 declared output fields
| Field | Type | Meaning |
|---|---|---|
type | string | hotel (a property with its price for the stay), room (one room and rate combination, only with includeRooms) or status (one per destination or property) |
hotel_id | string | Booking's numeric property id |
ufi | integer | Booking's city/area id (negative numbers are cities) |
name | string | |
url | string | The Booking.com property page |
property_type | string | hotel, apartment, hostel, bed_and_breakfast, guest_house, holiday_home, villa, resort, homestay, motel, aparthotel, campsite, lodge, capsule_hotel, inn — or null for rarer types (see property_type_id) |
property_type_id | integer | Booking's accommodation type id |
stars | number | Star rating as shown by Booking (null when the property has none) |
review_score | number | Booking guest score, 1-10 |
review_count | integer | |
address | string | |
city | string | |
country_code | string | ISO 3166-1 alpha-2, lower case |
latitude | number | |
longitude | number | |
display_location | string | Booking's location line, e.g. 'Alfama, Lisbon' |
distance_from_center | string | e.g. '0.8 km from downtown' |
transport | string | e.g. 'Terreiro do Paço station is within 500 meters' |
check_in | string | YYYY-MM-DD |
check_out | string | YYYY-MM-DD |
nights | integer | |
adults | integer | |
children | integer | |
rooms | integer | Rooms requested |
currency | string | The currency of price_total and price_nightly (your `currency` input) |
price_total | number | Booking displayPrice.amountPerStay on hotel rows, or the matching block finalPrice on room rows. Reported stay amount, not a verified final payable total; null means the source supplied no parsed price. |
price_nightly | number | price_total ÷ nights |
price_display | string | Booking's formatted total, e.g. 'US$482.38' |
price_hotel_currency_total | number | The same stay total in the property's own currency |
hotel_currency | string | |
price_before_discount | number | The crossed-out total when a deal applies (0 or null when none) |
taxes_fees_excluded | number | Reported excludeChargesAggregated.amountPerStay. Null means unavailable, not proof that all charges are included. Exhaustiveness, party adjustment and non-overlap are not verified; the aggregate's separate currency is not retained. |
taxes_included | boolean | Legacy derived indicator: with a non-null price_total, true when the excluded aggregate is missing or zero; false when nonzero. It does not verify inclusion of all mandatory charges. Null when price_total is null. |
charges_note | string | Booking chargesInfo.translation when supplied. Null is missing text, not proof that no additional charges or conditions apply. |
free_cancellation | boolean | Hotel row: bool(policies.showFreeCancellation). Room row: whether freeCancellationUntil text exists. False includes missing information; neither value supplies a complete cancellation policy or penalty schedule. |
no_prepayment | boolean | Hotel-level showNoPrepayment badge converted to boolean. False includes an absent badge and does not prove advance payment is required; no amount or payment schedule is provided. |
meal_plan | string | Hotel-level mealPlanIncluded.text on hotel rows; the matching block mealPlanIncluded.text on room rows. Hotel summary fields are not proven to describe one identical cheapest rate. |
breakfast_included | boolean | Whether the hotel-level meal-plan text contains the English word breakfast. False can reflect absent or localized text; this is not a verified same-rate meal entitlement. |
room_name | string | Hotel row: name of the block with the lowest numeric finalPrice.amount, selected separately from the headline display price. Room row: the matching block roomId's unit name. Not a verified headline-rate join. |
rooms_listed | integer | Number of dictionary-valued blocks returned with the hotel result. Not complete property inventory and not necessarily the number delivered after a spending limit. |
sold_out | boolean | True when Booking shows no price for these dates |
sold_out_message | string | |
alternative_check_in | string | Booking's suggested dates when the stay is unavailable |
alternative_check_out | string | |
sponsored | boolean | A paid placement in the results |
newly_opened | boolean | |
sustainable | boolean | |
host_type | string | PROFESSIONAL or PRIVATE, when Booking states it |
image | string | |
query | string | The destination or hotel target this row came from |
rank | integer | Position in the destination results under sortBy (1 = first) |
hotel_name | string | On room and status rows |
room_id | string | |
occupancy | integer | Guests the block is priced for |
meal_plan_id | integer | |
policy_group_id | string | |
price_original | number | The matching block originalPrice amount, with original_currency. This is not independently verified as the hotel-currency price. |
original_currency | string | Currency supplied with the block originalPrice; it need not be treated as proof of the property's native currency. |
free_cancellation_until | string | Source freeCancellationUntil text for the matching room block; nullable, not normalized to a timezone, and not a complete cancellation penalty contract. |
only_x_left | string | e.g. 'Only 2 left at this price on our site' |
has_crib | boolean | |
third_party | boolean | |
target | string | The destination or hotel target as given |
kind | string | destination or hotel |
dest_id | integer | |
dest_type | string | CITY, REGION, DISTRICT, LANDMARK, AIRPORT, COUNTRY or HOTEL |
status | string | ok, no_results, not_found, duplicate or error |
hotels | integer | |
priced | integer | Charged rows |
unpriced | integer | Delivered free |
filtered | integer | Dropped by maxPrice before billing |
duplicates | integer | Properties already delivered by another target |
pages | integer | |
total | integer | Booking's result count for the destination |
error | string | |
fetched_at | string | Actor UTC timestamp when the emitted row is constructed after parsing. Not a Booking price-acquisition timestamp or a guarantee about upstream cache age. |
Start with a small sample
Use call-actor with the JSON below. The $0.25 run ceiling is separate from the Actor input and may stop the sample early. Change the target to match your request. This input validates against build 1.2.5; it is not a promise that the source has matching rows today.
{
"actor": "kestrel/booking-prices-scraper",
"input": {
"locationQueries": [
"Lisbon"
],
"maxHotelsPerQuery": 3,
"checkIn": "30 days",
"nights": 1,
"adults": 2,
"currency": "USD",
"sortBy": "price"
},
"callOptions": {
"maxTotalChargeUsd": 0.25,
"timeout": 300
},
"waitSecs": 30
}
After completion, use get-dataset-items with storages.datasets.default.id. If still running, poll get-actor-run using the returned runId. Check status rows and errors before treating an empty dataset as no matches.
Call from Python, JavaScript or REST
Python SDK 3 example · JavaScript SDK 2 example · curl + jq example. Each uses this same small input, reads APIFY_TOKEN from your environment, sets a five-minute run timeout and exports all dataset row types as JSON Lines. The $0.25 run ceiling is separate from the Actor input and may stop the sample early. Inspect the run and source status before treating results as complete. Installation and usage.
Pricing and limits
Current listed event prices in USD. Some Actors charge for successful source checks even when no output rows match. The event descriptions below define those differences.
| Event | USD each | What is charged |
|---|---|---|
hotel | $0.004 | One delivered Booking.com hotel row with a non-null reported stay price: $4 per 1,000 rows. Row keys include hotel_id, name, price_total, price_nightly, currency, taxes_fees_excluded, taxes_included, free_cancellation, no_prepayment, breakfast_included, room_name, check_in and check_out. Reported prices and badges are search-result indicators, not a verified payable total or complete same-rate policy/eligibility contract; missing badge data can become false. Unpriced/sold-out hotel rows, filtered rows, duplicates, status rows, bad input and failed/empty searches are not charged. No start fee; proxy and compute are included. maxTotalChargeUsd is an Apify run option; the run stops at that ceiling. |
room | $0.002 | One delivered matching room/rate block from Booking's returned search result, only when includeRooms=true: $2 per 1,000 rows. Row keys include hotel_id, room_id, room_name, occupancy, meal_plan, meal_plan_id, policy_group_id, price_total, currency, price_original, original_currency, free_cancellation_until and only_x_left. Optional source fields, including price, can be null. original_currency belongs to the block originalPrice; it is not verified as hotel currency. Cancellation text is not a complete penalty/payment contract. These blocks are not exhaustive inventory. rooms_listed counts returned blocks before the run spending cap; no separate room cap. No charge when includeRooms=false. No start fee; proxy and compute included. |
Contracts for agents
- Input schema and sample input
- Prepared MCP call and pricing events
- Full Actor instructions and limits
- REST API
Public contract checked 2026-11-11. Active build: 1.2.5. Refresh live details before a large or recurring run.