# BookingScraper (`scrapebase/bookingscraper`) Actor - **URL**: https://apify.com/scrapebase/bookingscraper.md - **Developed by:** [ScrapeBase](https://apify.com/scrapebase) (community) - **Categories:** Automation, Lead generation, Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $19.99/month + usage To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## BookingScraper Apify Actor **BookingScraper** scrapes **Booking.com** hotel detail pages and optional search results. It produces output in the same format as the reference (e.g. `output.json`): one JSON object per hotel with `order`, `url`, `startUrlOrQuery`, `name`, `type`, `description`, `stars`, `price`, `currency`, `rating`, `ratingLabel`, `reviews`, `breakfast`, `checkIn`/`checkOut`, `checkInDate`/`checkOutDate`, `location`, `address`, `image`, `rooms`, `highlights`, `finePrint`, `policies`, `images`, `roomImages`, `categoryReviews`, `hotelChain`, `licenseInfo`, `hostInfo`, `traderInfo`, `breadcrumbs`, `hotelId`, `facilities`, `timeOfScrapeISO`, and optional `source_url`. By default it uses **no proxy**; if Booking.com blocks or rejects requests, it automatically falls back to **datacenter** then **residential** proxy (with up to 3 retries), and logs all proxy events clearly. --- ### Why Choose Us? - **Same output shape as your reference**: Produces one JSON object per hotel with `order`, `url`, `name`, `type`, `description`, `stars`, `price`, `currency`, `rating`, `ratingLabel`, `reviews`, `rooms`, `images`, `roomImages`, `facilities`, `traderInfo`, `address`, `location`, `checkIn`/`checkOut`, `breadcrumbs`, `categoryReviews`, and more. - **Robust proxy handling**: No proxy by default; automatic fallback to datacenter then residential with clear `[PROXY]` logs. - **Live saving**: Each hotel is pushed to the dataset as soon as it’s scraped, so partial results are kept if the run stops. - **Bulk URLs**: Supply many hotel or search URLs in one run. - **Optional search**: Provide a search query (e.g. `"New York"`) and optional dates/filters to discover hotels from search results. --- ### Key Features | Feature | Description | |--------|-------------| | **Hotel detail scraping** | Full extraction from Booking.com hotel pages (Apollo state, schema.org, HTML fallbacks). | | **Search results** | Optionally scrape from search URLs or a search query to get a list of hotels, then scrape each. | | **Proxy fallback** | NO_PROXY → DATACENTER → RESIDENTIAL (3 retries); once on residential, all remaining requests use it. | | **Detailed logs** | Progress and proxy events logged so you can follow the run until the final result. | | **Retries** | Failed requests trigger proxy fallback or residential retry so the actor recovers from blocks. | --- ### Input Configure the actor with the Apify input schema. Example: ```json { "urls": [ { "url": "https://www.booking.com/hotel/us/trump-international-new-york.en-gb.html" } ], "proxyConfiguration": { "useApifyProxy": false }, "maxItems": 10, "search": "New York", "checkIn": "2026-03-25", "checkOut": "2026-03-31" } ```` | Field | Type | Description | |-------|------|-------------| | **urls** | array | **Required** (or use `search`). List of Booking.com hotel page URLs or search results page URLs. Each item can be `{ "url": "..." }` or a string. | | **proxyConfiguration** | object | Proxy settings. Default: no proxy. Use Apify proxy if you want; fallback will use datacenter/residential when needed. | | **maxItems** | integer | Max number of hotels to scrape when using search or search result URLs (default: 10). | | **search** | string | If no URLs (or only search URLs), use this as the location/landmark (e.g. `"New York"`). | | **checkIn** / **checkOut** | string | Optional dates in `YYYY-MM-DD` for search. | *** ### Output The default dataset contains one item per scraped hotel. Each item matches the structure of your reference output, for example: ```json { "order": 1, "url": "https://www.booking.com/hotel/us/trump-international-new-york.en-gb.html", "startUrlOrQuery": "New York", "name": "Trump International New York", "type": "hotel", "description": "Located at the juncture of Columbus Circle and Broadway...", "stars": 5, "price": 3067.11, "currency": "USD", "rating": 8.9, "ratingLabel": "Very good", "reviews": 842, "breakfast": "Available", "checkIn": "From 16:00 to None", "checkOut": "From None to 12:00", "checkInDate": "2026-03-25", "checkOutDate": "2026-03-31", "location": { "lat": 40.769, "lng": -73.981 }, "address": { "full": "One Central Park West", "country": "US", "city": "New York" }, "image": "https://cf.bstatic.com/...", "rooms": [...], "highlights": [...], "finePrint": "...", "policies": [...], "images": [...], "roomImages": [...], "categoryReviews": [...], "hotelChain": null, "licenseInfo": null, "hostInfo": null, "traderInfo": { "isBusiness": true, "email": "...", "phone": "...", "address": {...} }, "breadcrumbs": [...], "hotelId": "...", "facilities": [...], "source_url": "https://www.booking.com/...", "timeOfScrapeISO": "2026-03-15T12:00:00.000000+00:00" } ``` | Field | Description | |-------|-------------| | **order** | 1-based index of the hotel in this run. | | **url** / **source\_url** | Canonical and requested URL. | | **name**, **type**, **description** | Basic property info. | | **stars**, **price**, **currency** | Star rating and price. | | **rating**, **ratingLabel**, **reviews** | Guest rating and count. | | **rooms** | Room types with id, name, price when available. | | **images**, **roomImages** | Main and per-room image URLs. | | **traderInfo** | Business/contact and address. | | **facilities**, **highlights** | Amenities and highlights. | | **timeOfScrapeISO** | When the page was scraped (UTC). | *** ### How to Use the Actor (Apify Console) 1. Log in at and go to **Actors**. 2. Find **booking-hotel-scraper** (or your actor name) and open it. 3. Set **Input**: - **urls**: Add one or more Booking.com hotel or search URLs (or use **search** and optional dates). - **proxyConfiguration**: Leave default (no proxy) or enable Apify Proxy; fallback will be used automatically if needed. 4. Click **Start**. 5. Watch **Log** for progress and `[PROXY]` messages. 6. Open the **Output** tab to see the dataset (table or JSON). 7. Export to JSON/CSV if needed. *** ### Best Use Cases - **Hotel data for travel/price tools**: Get structured details for many properties. - **Competitor or market research**: Collect names, prices, ratings, facilities. - **Lead or contact data**: Use `traderInfo` (email, phone, company, address) from listing pages. *** ### Frequently Asked Questions **Do I need to enable proxy?**\ No. By default the actor sends requests without proxy. Enable Apify Proxy in input if you want; the actor will still start without proxy and only switch to datacenter/residential when it detects blocks. **What if I get blocked?**\ The actor will log `[PROXY]` and switch to datacenter, then residential. After switching to residential it keeps using it for all remaining requests. If residential fails, it retries up to 3 times and then fails the run with a clear message. **Can I scrape only from a search query?**\ Yes. Leave **urls** empty and set **search** (e.g. `"New York"`). Optionally set **checkIn**, **checkOut**, and **maxItems**. **Is the output format stable?**\ Yes. The output matches the same structure as the reference dataset (order, url, name, price, rooms, traderInfo, etc.). *** ### Support and Feedback Use the Apify platform support or your team’s channel for bugs or feature requests. Ensure your use complies with Booking.com’s terms and applicable law. *** ### Cautions - Data is collected only from **publicly available** Booking.com pages. - You are responsible for **legal compliance** (privacy, data protection, terms of use). - Use reasonable **maxItems** and **rate** to avoid overloading the target site. # Actor input Schema ## `search` (type: `string`): City, region, or landmark to search for accommodation (e.g. New York, Paris). ## `startUrls` (type: `array`): Add one or more Booking.com URLs: hotel detail pages or search results pages. Use Add, Bulk edit, or paste URLs. ## `maxItems` (type: `integer`): Maximum number of hotels to scrape per destination or per start URL. ## `scrapeAdditionalHotelData` (type: `boolean`): Extract full hotel data including rooms, facilities, trader info, and images for each property. ## `propertyType` (type: `string`): Filter by type of accommodation. ## `sortBy` (type: `string`): How to sort search results. ## `minimumRating` (type: `string`): Minimum guest rating (e.g. 7, 8, 9). Leave empty for no filter. ## `starsCountFilter` (type: `string`): Filter by star rating. ## `currency` (type: `string`): Currency for displayed prices. ## `language` (type: `string`): Interface language for the search. ## `checkIn` (type: `string`): Select absolute date (YYYY-MM-DD) or relative (e.g. 2 weeks). Leave empty for flexible search. ## `checkOut` (type: `string`): Select absolute date (YYYY-MM-DD) or relative (e.g. 1 week). Leave empty for flexible search. ## `flexWindow` (type: `string`): Allow dates to shift by this many days. Use 0 for exact dates only. ## `rooms` (type: `integer`): Number of rooms for the stay. ## `adults` (type: `integer`): Number of adult guests. ## `children` (type: `integer`): Number of children. ## `minMaxPrice` (type: `string`): Min-max price filter, e.g. 50-200 or 100+ for minimum only. ## `proxyConfiguration` (type: `object`): By default no proxy is used. If Booking.com blocks requests, the actor falls back to datacenter then residential proxy. ## Actor input object example ```json { "search": "New York", "startUrls": [], "maxItems": 10, "scrapeAdditionalHotelData": true, "propertyType": "none", "sortBy": "distance_from_search", "minimumRating": "", "starsCountFilter": "any", "currency": "USD", "language": "en-gb", "checkIn": "", "checkOut": "", "flexWindow": "0", "rooms": 1, "adults": 2, "children": 0, "minMaxPrice": "0-999999", "proxyConfiguration": { "useApifyProxy": false } } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "search": "New York", "startUrls": [], "maxItems": 10, "scrapeAdditionalHotelData": true, "propertyType": "none", "sortBy": "distance_from_search", "minimumRating": "", "starsCountFilter": "any", "currency": "USD", "language": "en-gb", "checkIn": "", "checkOut": "", "flexWindow": "0", "rooms": 1, "adults": 2, "children": 0, "minMaxPrice": "0-999999", "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("scrapebase/bookingscraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "search": "New York", "startUrls": [], "maxItems": 10, "scrapeAdditionalHotelData": True, "propertyType": "none", "sortBy": "distance_from_search", "minimumRating": "", "starsCountFilter": "any", "currency": "USD", "language": "en-gb", "checkIn": "", "checkOut": "", "flexWindow": "0", "rooms": 1, "adults": 2, "children": 0, "minMaxPrice": "0-999999", "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("scrapebase/bookingscraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "search": "New York", "startUrls": [], "maxItems": 10, "scrapeAdditionalHotelData": true, "propertyType": "none", "sortBy": "distance_from_search", "minimumRating": "", "starsCountFilter": "any", "currency": "USD", "language": "en-gb", "checkIn": "", "checkOut": "", "flexWindow": "0", "rooms": 1, "adults": 2, "children": 0, "minMaxPrice": "0-999999", "proxyConfiguration": { "useApifyProxy": false } }' | apify call scrapebase/bookingscraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=scrapebase/bookingscraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "BookingScraper", "version": "0.1", "x-build-id": "xAbSIvBY1A4T0MUn1" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapebase~bookingscraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapebase-bookingscraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/scrapebase~bookingscraper/runs": { "post": { "operationId": "runs-sync-scrapebase-bookingscraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/scrapebase~bookingscraper/run-sync": { "post": { "operationId": "run-sync-scrapebase-bookingscraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "search": { "title": "Destination", "type": "string", "description": "City, region, or landmark to search for accommodation (e.g. New York, Paris).", "default": "New York" }, "startUrls": { "title": "Or use Start URLs instead", "type": "array", "description": "Add one or more Booking.com URLs: hotel detail pages or search results pages. Use Add, Bulk edit, or paste URLs.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxItems": { "title": "Max results per destination or URL", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum number of hotels to scrape per destination or per start URL.", "default": 10 }, "scrapeAdditionalHotelData": { "title": "Scrape additional hotel data", "type": "boolean", "description": "Extract full hotel data including rooms, facilities, trader info, and images for each property.", "default": true }, "propertyType": { "title": "Property type", "enum": [ "none", "hotels", "apartments", "hostels", "guest houses", "homestays", "bed and breakfasts", "holiday homes", "boats", "villas", "motels", "resorts", "holiday parks", "campsites", "luxury tents" ], "type": "string", "description": "Filter by type of accommodation.", "default": "none" }, "sortBy": { "title": "Order results by", "enum": [ "distance_from_search", "price", "review_score_and_price", "review_score", "star_rating" ], "type": "string", "description": "How to sort search results.", "default": "distance_from_search" }, "minimumRating": { "title": "Minimum rating", "type": "string", "description": "Minimum guest rating (e.g. 7, 8, 9). Leave empty for no filter.", "default": "" }, "starsCountFilter": { "title": "Stars count", "enum": [ "any", "3", "4", "5", "1", "2" ], "type": "string", "description": "Filter by star rating.", "default": "any" }, "currency": { "title": "Preferred currency", "enum": [ "USD", "EUR", "GBP", "CAD", "AUD", "CHF", "JPY", "CNY", "INR", "BRL", "MXN" ], "type": "string", "description": "Currency for displayed prices.", "default": "USD" }, "language": { "title": "Language", "enum": [ "en-gb", "en-us", "de", "fr", "es", "it", "pt-br", "nl", "pl", "ru", "ja", "zh" ], "type": "string", "description": "Interface language for the search.", "default": "en-gb" }, "checkIn": { "title": "Check-in date", "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$|^(\\d+)\\s*(day|week|month|year)s?$|^$", "type": "string", "description": "Select absolute date (YYYY-MM-DD) or relative (e.g. 2 weeks). Leave empty for flexible search.", "default": "" }, "checkOut": { "title": "Check-out date", "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$|^(\\d+)\\s*(day|week|month|year)s?$|^$", "type": "string", "description": "Select absolute date (YYYY-MM-DD) or relative (e.g. 1 week). Leave empty for flexible search.", "default": "" }, "flexWindow": { "title": "Stay date flexibility (days)", "enum": [ "0", "1", "2", "3", "7" ], "type": "string", "description": "Allow dates to shift by this many days. Use 0 for exact dates only.", "default": "0" }, "rooms": { "title": "Number of rooms", "minimum": 1, "maximum": 9, "type": "integer", "description": "Number of rooms for the stay.", "default": 1 }, "adults": { "title": "Number of adults", "minimum": 1, "maximum": 30, "type": "integer", "description": "Number of adult guests.", "default": 2 }, "children": { "title": "Number of children", "minimum": 0, "maximum": 30, "type": "integer", "description": "Number of children.", "default": 0 }, "minMaxPrice": { "title": "Price range", "type": "string", "description": "Min-max price filter, e.g. 50-200 or 100+ for minimum only.", "default": "0-999999" }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "By default no proxy is used. If Booking.com blocks requests, the actor falls back to datacenter then residential proxy." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```