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
FieldTypeMeaning
typestringhotel (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_idstringBooking's numeric property id
ufiintegerBooking's city/area id (negative numbers are cities)
namestring
urlstringThe Booking.com property page
property_typestringhotel, 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_idintegerBooking's accommodation type id
starsnumberStar rating as shown by Booking (null when the property has none)
review_scorenumberBooking guest score, 1-10
review_countinteger
addressstring
citystring
country_codestringISO 3166-1 alpha-2, lower case
latitudenumber
longitudenumber
display_locationstringBooking's location line, e.g. 'Alfama, Lisbon'
distance_from_centerstringe.g. '0.8 km from downtown'
transportstringe.g. 'Terreiro do Paço station is within 500 meters'
check_instringYYYY-MM-DD
check_outstringYYYY-MM-DD
nightsinteger
adultsinteger
childreninteger
roomsintegerRooms requested
currencystringThe currency of price_total and price_nightly (your `currency` input)
price_totalnumberBooking 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_nightlynumberprice_total ÷ nights
price_displaystringBooking's formatted total, e.g. 'US$482.38'
price_hotel_currency_totalnumberThe same stay total in the property's own currency
hotel_currencystring
price_before_discountnumberThe crossed-out total when a deal applies (0 or null when none)
taxes_fees_excludednumberReported 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_includedbooleanLegacy 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_notestringBooking chargesInfo.translation when supplied. Null is missing text, not proof that no additional charges or conditions apply.
free_cancellationbooleanHotel 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_prepaymentbooleanHotel-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_planstringHotel-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_includedbooleanWhether 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_namestringHotel 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_listedintegerNumber of dictionary-valued blocks returned with the hotel result. Not complete property inventory and not necessarily the number delivered after a spending limit.
sold_outbooleanTrue when Booking shows no price for these dates
sold_out_messagestring
alternative_check_instringBooking's suggested dates when the stay is unavailable
alternative_check_outstring
sponsoredbooleanA paid placement in the results
newly_openedboolean
sustainableboolean
host_typestringPROFESSIONAL or PRIVATE, when Booking states it
imagestring
querystringThe destination or hotel target this row came from
rankintegerPosition in the destination results under sortBy (1 = first)
hotel_namestringOn room and status rows
room_idstring
occupancyintegerGuests the block is priced for
meal_plan_idinteger
policy_group_idstring
price_originalnumberThe matching block originalPrice amount, with original_currency. This is not independently verified as the hotel-currency price.
original_currencystringCurrency supplied with the block originalPrice; it need not be treated as proof of the property's native currency.
free_cancellation_untilstringSource freeCancellationUntil text for the matching room block; nullable, not normalized to a timezone, and not a complete cancellation penalty contract.
only_x_leftstringe.g. 'Only 2 left at this price on our site'
has_cribboolean
third_partyboolean
targetstringThe destination or hotel target as given
kindstringdestination or hotel
dest_idinteger
dest_typestringCITY, REGION, DISTRICT, LANDMARK, AIRPORT, COUNTRY or HOTEL
statusstringok, no_results, not_found, duplicate or error
hotelsinteger
pricedintegerCharged rows
unpricedintegerDelivered free
filteredintegerDropped by maxPrice before billing
duplicatesintegerProperties already delivered by another target
pagesinteger
totalintegerBooking's result count for the destination
errorstring
fetched_atstringActor 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.

EventUSD eachWhat is charged
hotel$0.004One 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.002One 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

Public contract checked 2026-11-11. Active build: 1.2.5. Refresh live details before a large or recurring run.