# Booking.com Review Scraper (`noraview/booking-com-review-scraper`) Actor Which room type gets the complaints? What do guests really say about your breakfast? Scrape Booking.com reviews at room level โ€” score, liked/disliked texts, stay details, traveler type, management replies โ€” with score-band filters and topic search. Deduplicated, LLM-ready. - **URL**: https://apify.com/noraview/booking-com-review-scraper.md - **Developed by:** [NoraView Intelligence](https://apify.com/noraview) (community) - **Categories:** Travel, AI - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.50 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## ๐Ÿ’ฌ Booking.com Review Scraper **Room-level guest review corpus for any Booking.com hotel** โ€” up to a few hundred of the newest reviews per hotel, one clean record per review. Built as a data foundation for revenue managers and LLM pipelines: sampling, summarization and sentiment analysis happen downstream; this actor's job is to return a complete, deduplicated, structured corpus โ€” fast and cheap. Instead of rendering heavy hotel pages, this actor queries the same internal review endpoint Booking's own review panel uses. One page load per hotel, then light JSON calls (25 reviews per call) โ€” a fraction of the proxy cost of page-scraping actors. ### Why this scraper? - ๐Ÿ›๏ธ **Room-level granularity** โ€” every review carries the room stayed in, plus Booking's `booking_room_id`, so you can join reviews directly against room-level price data (e.g. the sibling [Booking.com Room-Level Price Tracker](https://apify.com/noraview)) - ๐ŸŽฏ **Server-side score filter** โ€” pull only the bands you need (Superb 9+ / Good 7-9 / Passable 5-7 / Poor 3-5 / Very poor 1-3). Booking does the filtering, you don't pay for pages you'll throw away - ๐Ÿ” **Topic search** โ€” same as Booking's "Search guest reviews by topic" bar: `breakfast`, `noise`, `wifi`, `pool`... Combines with the score filter - ๐Ÿงณ **Full stay context** โ€” nights, stay month, traveler type (solo/couple/family/group/business), reviewer country, review language - ๐Ÿ’ฌ **Management responses** โ€” property replies included - ๐Ÿงน **Corpus-ready** โ€” stable Booking review IDs, deduplicated, newest-first, score-only reviews kept and flagged (`has_text`) so they count toward evidence totals without polluting your LLM prompts --- ### ๐Ÿ“ฅ Input | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `hotelUrls` | array | โœ… | โ€” | Booking.com hotel URLs to scrape reviews for | | `maxReviewsPerHotel` | integer | โŒ | 200 | Newest reviews to collect per hotel (~8 pages at 200) | | `cutoffMonths` | integer | โŒ | 24 | Stop paginating once reviews are older than this โ€” beyond that, a review no longer describes the hotel as it is today | | `sort` | string | โŒ | Newest first | Newest first, Oldest first, Highest/Lowest score first, Most relevant | | `reviewScoreFilter` | array | โŒ | All | Score bands to include (server-side). Multiple bands = one pass per band, merged and deduplicated | | `searchText` | string | โŒ | โ€” | Topic search (Booking semantic search, like the site's own search bar) | | `useApifyProxy` | boolean | โŒ | true | Apify residential proxy โ€” Booking blocks datacenter IPs | | `proxyCountries` | array | โŒ | `["FR"]` | Proxy source market. Reviews are geo-independent โ€” one country is normal | | `proxyUrl` | string | โŒ | โ€” | External proxy (only if Apify Proxy is off) | | `delayBetweenRequests` | integer | โŒ | 2 | Seconds between review page fetches | #### Example input ```json { "hotelUrls": ["https://www.booking.com/hotel/th/karon-homes.html"], "maxReviewsPerHotel": 200, "cutoffMonths": 24, "sort": "f_recent_desc", "reviewScoreFilter": ["all"], "searchText": "", "useApifyProxy": true, "proxyCountries": ["FR"], "delayBetweenRequests": 2 } ```` #### Example: pain-point mining Only negative reviews mentioning the air conditioning, last 12 months: ```json { "hotelUrls": ["https://www.booking.com/hotel/ma/savoy-le-grand.html"], "maxReviewsPerHotel": 300, "cutoffMonths": 12, "reviewScoreFilter": ["passable", "poor", "very_poor"], "searchText": "air conditioning" } ``` *** ### ๐Ÿ“ค Output #### Review records (`record_type: "review"`) โ€” one per review | Field | Type | Description | |-------|------|--------------| | `review_id` | string | Booking's own stable review ID โ€” reliable dedup across runs | | `booking_hotel_id` | string | Booking's internal hotel ID | | `hotel_url` / `hotel_name` | string | Source hotel | | `review_date` | string | `YYYY-MM-DD` (UTC) | | `review_score` | number | 1โ€“10 | | `title` | string | Review title (often `null` โ€” Booking rarely returns titles anymore) | | `positive_text` | string | "Liked" text, in the reviewer's language | | `negative_text` | string | "Disliked" text | | `has_text` | boolean | `false` = score-only review: kept for evidence totals, skip it in LLM prompts | | `language` | string | Review language code from Booking (`en`, `ru`, `ar`...; `xu` = undetermined) | | `booking_room_id` | integer | Booking's room ID โ€” join key against room-level price data | | `room_name` | string | Raw room name ("Stayed in: โ€ฆ") | | `room_name_clean` | string | Bed-type suffix stripped | | `nights` | integer | Length of stay | | `stay_month` | string | `YYYY-MM` โ€” month of the stay (not the review date) | | `traveler_type` | string | `solo`, `couple`, `family`, `group` or `business` | | `traveler_type_raw` | string | Booking's raw enum (`SOLO_TRAVELLERS`, `COUPLES`...) | | `reviewer_country` | string | ISO-2 country code (`BR`, `DE`...) | | `mgmt_response_text` | string | Property's reply, if any | | `mgmt_response_date` | โ€” | Always `null` โ€” Booking no longer exposes the reply date via this endpoint | | `helpful_votes_count` | integer | "Helpful" votes (`null` on score-only reviews) | | `scrape_timestamp` | string | UTC timestamp of the run | #### Hotel summary records (`record_type: "hotel_summary"`) โ€” one per hotel Run metadata: `reviews_count_on_booking`, `reviews_scraped`, `pages_fetched`, `duplicates_dropped`, `sort`, `cutoff_months`, `score_filter`, `search_text`, `per_band` breakdown, and `stop_reason` (`max_reviews`, `cutoff`, `last_page`โ€ฆ). *** ### ๐Ÿ” How it works 1. **Bootstrap** โ€” loads the hotel page once to resolve Booking's internal hotel ID and destination ID 2. **Fetch** โ€” calls Booking's internal review endpoint (the one powering the on-site review panel): 25 reviews per call, newest first 3. **Stop conditions** โ€” `maxReviewsPerHotel` reached, no more reviews, or the oldest review on the page passes `cutoffMonths` (reviews arrive newest-first, so everything beyond that point is out of range too) Filters are applied **server-side**, exactly like Booking's own UI: the score filter maps to Booking's score bands, and `searchText` uses Booking's semantic topic search โ€” not a literal substring match, so it catches related wording (`breakfast` also matches "morning meal"). Match highlights are stripped from the text automatically. #### Anti-block infrastructure Rotating user-agents/viewports/timezones, a fresh browser context and proxy IP per hotel, resource blocking (images/fonts/tracking), cookie-consent and WAF challenge handling, exponential backoff on retry. Failed hotels produce an error record โ€” one bad IP never sinks the run. *** ### ๐Ÿš€ Use cases - **LLM sentiment pipelines** โ€” feed `has_text: true` reviews into summarization; keep score-only reviews in the evidence counts - **Room-level complaint analysis** โ€” join on `booking_room_id` / `room_name_clean` against the price tracker to find which room types get complaints, and whether they're priced accordingly - **Competitor benchmarking** โ€” track review velocity, score trends and topic mix across a comp set - **Pain-point mining** โ€” score filter + topic search to isolate exactly the reviews that cost you stars *** ### โš ๏ธ Notes & limitations - `mgmt_response_date` is always `null` โ€” Booking exposes the reply text only - Booking's topic search is semantic (same behavior as booking.com's own search bar); match counts are approximate by design - Review `title` is often `null` โ€” Booking rarely returns titles anymore ### ๐Ÿ“ Changelog #### v1.1.0 - Server-side **score-band filter** (Superb/Good/Passable/Poor/Very poor, multi-band merge + dedup) - Server-side **topic search** (`searchText`), combinable with the score filter - `` highlight stripping, `search_text` in summary records #### v1.0.0 - Initial release โ€” review corpus, pagination, 24-month cutoff, dedup by Booking review ID, proxy + retry infrastructure # Actor input Schema ## `hotelUrls` (type: `array`): Booking.com hotel URLs to scrape reviews for. ## `maxReviewsPerHotel` (type: `integer`): Newest reviews to collect per hotel (sorted newest first). ~200 = 8 pages. ## `cutoffMonths` (type: `integer`): Stop paginating once reviews are older than this many months โ€” beyond that a review no longer describes the hotel as it is today. ## `sort` (type: `string`): Booking.com review sort order. ## `reviewScoreFilter` (type: `array`): Filter reviews by score band (server-side, same as Booking's own filter โ€” no wasted pages). 'All' = no filter. Multiple bands = one pass per band, merged and deduplicated. ## `searchText` (type: `string`): Same as Booking's 'Search guest reviews by topic' bar โ€” server-side semantic search (e.g. 'breakfast', 'pool', 'noise', 'wifi'). Leave empty for no search. Combines with the score filter. ## `useApifyProxy` (type: `boolean`): OFF by default โ€” the scraper first tries cheap datacenter IPs. Turn ON only to force the residential proxy from the start (more expensive, rarely needed while auto fallback below is enabled). ## `autoProxyFallback` (type: `boolean`): Tries datacenter IPs first; if Booking blocks us (WAF / CAPTCHA / HTTP 403-429), the same hotel is automatically retried through Apify's residential proxy. Best cost/reliability balance. ## `proxyCountries` (type: `array`): Source markets to route the proxy through. Reviews are geo-independent โ€” this is only for proxy-pool diversity, not per-country cohorts. One country is normal. ## `proxyUrl` (type: `string`): Used only if 'Use Apify Proxy' is off. Format: http://user:pass@host:port ## `delayBetweenRequests` (type: `integer`): Wait time between each review page fetch. ## Actor input object example ```json { "hotelUrls": [ { "url": "https://www.booking.com/hotel/th/karon-homes.html", "method": "GET" } ], "maxReviewsPerHotel": 200, "cutoffMonths": 24, "sort": "f_recent_desc", "reviewScoreFilter": [ "all" ], "searchText": "", "useApifyProxy": false, "autoProxyFallback": true, "proxyCountries": [ "FR" ], "proxyUrl": "", "delayBetweenRequests": 2 } ``` # 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 = { "hotelUrls": [ { "url": "https://www.booking.com/hotel/th/karon-homes.html", "method": "GET" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("noraview/booking-com-review-scraper").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 = { "hotelUrls": [{ "url": "https://www.booking.com/hotel/th/karon-homes.html", "method": "GET", }] } # Run the Actor and wait for it to finish run = client.actor("noraview/booking-com-review-scraper").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 '{ "hotelUrls": [ { "url": "https://www.booking.com/hotel/th/karon-homes.html", "method": "GET" } ] }' | apify call noraview/booking-com-review-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=noraview/booking-com-review-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Booking.com Review Scraper", "description": "Which room type gets the complaints? What do guests really say about your breakfast? Scrape Booking.com reviews at room level โ€” score, liked/disliked texts, stay details, traveler type, management replies โ€” with score-band filters and topic search. Deduplicated, LLM-ready.", "version": "0.0", "x-build-id": "m1sQzb9LfGdA2X2lS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/noraview~booking-com-review-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-noraview-booking-com-review-scraper", "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/noraview~booking-com-review-scraper/runs": { "post": { "operationId": "runs-sync-noraview-booking-com-review-scraper", "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/noraview~booking-com-review-scraper/run-sync": { "post": { "operationId": "run-sync-noraview-booking-com-review-scraper", "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", "required": [ "hotelUrls" ], "properties": { "hotelUrls": { "title": "๐Ÿจ Hotel URLs", "type": "array", "description": "Booking.com hotel URLs to scrape reviews for.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxReviewsPerHotel": { "title": "๐Ÿ“Š Max Reviews per Hotel", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Newest reviews to collect per hotel (sorted newest first). ~200 = 8 pages.", "default": 200 }, "cutoffMonths": { "title": "๐Ÿ“… Cutoff (months)", "minimum": 1, "maximum": 120, "type": "integer", "description": "Stop paginating once reviews are older than this many months โ€” beyond that a review no longer describes the hotel as it is today.", "default": 24 }, "sort": { "title": "Sort Order", "enum": [ "f_recent_desc", "f_recent_asc", "f_score_desc", "f_score_asc", "f_relevance" ], "type": "string", "description": "Booking.com review sort order.", "default": "f_recent_desc" }, "reviewScoreFilter": { "title": "Review scores filter", "type": "array", "description": "Filter reviews by score band (server-side, same as Booking's own filter โ€” no wasted pages). 'All' = no filter. Multiple bands = one pass per band, merged and deduplicated.", "items": { "type": "string", "enum": [ "all", "superb", "good", "passable", "poor", "very_poor" ], "enumTitles": [ "All", "Superb: 9+", "Good: 7-9", "Passable: 5-7", "Poor: 3-5", "Very poor: 1-3" ] }, "default": [ "all" ] }, "searchText": { "title": "๐Ÿ” Search in reviews (optional)", "type": "string", "description": "Same as Booking's 'Search guest reviews by topic' bar โ€” server-side semantic search (e.g. 'breakfast', 'pool', 'noise', 'wifi'). Leave empty for no search. Combines with the score filter.", "default": "" }, "useApifyProxy": { "title": "Force Apify residential proxy", "type": "boolean", "description": "OFF by default โ€” the scraper first tries cheap datacenter IPs. Turn ON only to force the residential proxy from the start (more expensive, rarely needed while auto fallback below is enabled).", "default": false }, "autoProxyFallback": { "title": "๐Ÿ›ก๏ธ Auto fallback to residential proxy", "type": "boolean", "description": "Tries datacenter IPs first; if Booking blocks us (WAF / CAPTCHA / HTTP 403-429), the same hotel is automatically retried through Apify's residential proxy. Best cost/reliability balance.", "default": true }, "proxyCountries": { "title": "Proxy Countries", "type": "array", "description": "Source markets to route the proxy through. Reviews are geo-independent โ€” this is only for proxy-pool diversity, not per-country cohorts. One country is normal.", "default": [ "FR" ], "items": { "type": "string" } }, "proxyUrl": { "title": "External Proxy URL (optional)", "type": "string", "description": "Used only if 'Use Apify Proxy' is off. Format: http://user:pass@host:port", "default": "" }, "delayBetweenRequests": { "title": "Delay Between Page Requests (seconds)", "minimum": 1, "maximum": 10, "type": "integer", "description": "Wait time between each review page fetch.", "default": 2 } } }, "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 } } } } } } } } } } ```