{ "openapi": "3.0.1", "info": { "title": "Booking Reviews Scraper — Hotels & Monitor", "description": "Booking.com reviews scraper for hotel intelligence. Discover properties by name or destination, export scores, text, guest/stay/room data, photos and partner replies, filter by traveler/language/date/stay details, run summary-only benchmarks, and monitor only new reviews.", "version": "0.1", "x-build-id": "sGB5spMujHNByXLir" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/zenomastro~booking-reviews-reliable/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-zenomastro-booking-reviews-reliable", "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/zenomastro~booking-reviews-reliable/runs": { "post": { "operationId": "runs-sync-zenomastro-booking-reviews-reliable", "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/zenomastro~booking-reviews-reliable/run-sync": { "post": { "operationId": "run-sync-zenomastro-booking-reviews-reliable", "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": { "hotelUrls": { "title": "Booking.com hotel URLs", "minItems": 0, "maxItems": 100, "type": "array", "description": "Booking.com hotel pages to scrape, one URL per line, e.g. https://www.booking.com/hotel/us/ace-new-york.html. Any Booking.com property page works (hotels, apartments, B&Bs). Leave empty when you use start URLs, hotel searches or discovery URLs below.", "items": { "type": "string" } }, "maxReviewsPerHotel": { "title": "Maximum reviews per hotel", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum review rows returned (and billed) per hotel after filters, e.g. 200 (up to 5,000). Popular hotels have several thousand reviews on Booking.com.", "default": 500 }, "maxTotalReviews": { "title": "Maximum total reviews", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Hard cap on review rows across all hotels in this run, e.g. 1000, for predictable runtime and spend.", "default": 5000 }, "sortBy": { "title": "Review order", "enum": [ "newest", "most_relevant", "oldest", "score_desc", "score_asc" ], "type": "string", "description": "Order in which Booking.com returns reviews: newest, most relevant, oldest, highest score or lowest score first (e.g. 'Lowest score first' to read complaints first). Uses Booking.com's own sort options. With 'Newest first' or 'Oldest first' and a reviewed date range, the Actor jumps straight to that period, so even a month several years back is reached in a few requests.", "default": "newest" }, "startUrls": { "title": "Start URLs with your own IDs", "maxItems": 100, "type": "array", "description": "Optional. Same as hotel URLs, plus your own data per URL (userData, under Advanced in the editor), which is returned unchanged as customData on every row of that hotel, e.g. {\"crmId\": \"H-1\"}, to join the results with your CRM or sheet. Through the API you can also pass rows of a Booking.com hotel dataset that have a url or hotelUrl field.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "hotelSearchQueries": { "title": "Hotel or destination searches", "maxItems": 25, "type": "array", "description": "Optional. Find hotels by name or destination on Booking.com, e.g. 'Ace Hotel New York' or 'hotels in Lisbon', then scrape reviews of the properties found (best effort; pasting hotel URLs is fastest).", "default": [], "items": { "type": "string" } }, "discoveryUrls": { "title": "Booking.com discovery/search URLs", "maxItems": 25, "type": "array", "description": "Optional. Booking.com search or destination pages whose hotel links become review targets, e.g. https://www.booking.com/searchresults.html?ss=Lisbon (best effort: the links visible on the page are used).", "default": [], "items": { "type": "string" } }, "maxDiscoveredHotels": { "title": "Maximum discovered hotels", "minimum": 1, "maximum": 200, "type": "integer", "description": "Maximum number of hotels taken from hotel searches and discovery URLs together, e.g. 20.", "default": 50 }, "minScore": { "title": "Minimum review score", "minimum": 1, "maximum": 10, "type": "number", "description": "Only return reviews scored at or above this value on Booking.com's 1-10 scale, e.g. 8 for happy guests.", "default": 1 }, "maxScore": { "title": "Maximum review score", "minimum": 1, "maximum": 10, "type": "number", "description": "Only return reviews scored at or below this value on Booking.com's 1-10 scale, e.g. 5 to collect complaints.", "default": 10 }, "reviewedAfter": { "title": "Reviewed after", "type": "string", "description": "Only reviews written on or after this date: YYYY-MM-DD (e.g. 2026-01-01), ISO 8601, or a relative value counted back from the run start such as '7 days', '2 weeks' or '3 months' (ideal for schedules). With newest or oldest order the Actor jumps straight to the requested period.", "default": "" }, "reviewedBefore": { "title": "Reviewed before", "type": "string", "description": "Only reviews written on or before this date: YYYY-MM-DD (e.g. 2026-06-30), ISO 8601, or a relative value such as '30 days'. With newest or oldest order the Actor jumps straight to the requested period.", "default": "" }, "languageCodes": { "title": "Review languages", "type": "array", "description": "Only reviews written in these languages, e.g. en, it, de, fr. A code without region such as en includes all its variants (Booking.com's en, en-gb and xu = US English); a regional code such as en-us (or xu) or pt-br (or xb) includes only that variant. Empty means all languages.", "default": [], "items": { "type": "string" } }, "customerTypes": { "title": "Traveler types", "type": "array", "description": "Only these traveler types: COUPLES, SOLO_TRAVELLERS, FAMILIES, GROUP_OF_FRIENDS or BUSINESS_TRAVELLERS. Empty means all traveler types.", "default": [], "items": { "type": "string" } }, "reviewerCountries": { "title": "Reviewer countries", "type": "array", "description": "Only reviews from guests of these countries, as country codes or names, e.g. us, gb, Italy. Empty means all countries.", "default": [], "items": { "type": "string" } }, "containsText": { "title": "Review text contains", "type": "string", "description": "Only reviews whose title, positive or negative text contains this phrase (case-insensitive), e.g. breakfast. Filtered-out reviews are not billed.", "default": "" }, "minHelpfulVotes": { "title": "Minimum helpful votes", "minimum": 0, "type": "integer", "description": "Only reviews that at least this many readers marked as helpful, e.g. 1. 0 means no minimum.", "default": 0 }, "partnerReply": { "title": "Hotel reply", "enum": [ "any", "yes", "no" ], "type": "string", "description": "Return any reviews, only reviews with a reply from the property, or only reviews without one, e.g. to find unanswered complaints.", "default": "any" }, "stayAfter": { "title": "Stay/check-in after", "type": "string", "description": "Only reviews from stays that started (check-in) on or after this date: YYYY-MM-DD, e.g. 2026-06-01, or a relative value such as '6 months'.", "default": "" }, "stayBefore": { "title": "Stay/check-in before", "type": "string", "description": "Only reviews from stays that started (check-in) on or before this date: YYYY-MM-DD, e.g. 2026-08-31.", "default": "" }, "minNights": { "title": "Minimum nights stayed", "minimum": 0, "maximum": 365, "type": "integer", "description": "Only reviews from stays of at least this many nights, e.g. 3. 0 means no minimum.", "default": 0 }, "maxNights": { "title": "Maximum nights stayed", "minimum": 0, "maximum": 365, "type": "integer", "description": "Only reviews from stays of at most this many nights, e.g. 2 for short city breaks. Leave empty for no maximum." }, "roomContains": { "title": "Room type contains", "type": "string", "description": "Only reviews whose room type name contains this text (case-insensitive), e.g. suite or king.", "default": "" }, "includePhotos": { "title": "Include review photos", "type": "boolean", "description": "Include the public photo URLs that guests attached to their reviews. Turn off for smaller rows; photoCount still says how many photos a review has.", "default": true }, "includeHotelSummary": { "title": "Include hotel summary", "type": "boolean", "description": "Add one free hotel_summary row per hotel with the total review count, category sub-scores (staff, cleanliness, location, ...), score, language and traveler-type breakdowns from Booking.com, and the sort order applied.", "default": true }, "includeReviewInsights": { "title": "Include review insights", "type": "boolean", "description": "Add one free review_insights row per hotel over the returned reviews: average score, hotel reply rate, score distribution, traveler types, languages, top guest countries, average nights and share of reviews with photos.", "default": true }, "includeReviewerInfo": { "title": "Include guest names", "type": "boolean", "description": "The guest's display name on each review. Turn off to collect reviews without guests' names (data minimisation, e.g. for GDPR); scores, texts, country, traveler type, stay details and hotel replies stay.", "default": true }, "summaryOnly": { "title": "Hotel summary only", "type": "boolean", "description": "Return only hotel review counts and rating/filter aggregates, without review rows. Charged per hotel summary (event 'hotel-summary'). Useful for fast property benchmarking.", "default": false }, "monitorName": { "title": "Review monitor name", "type": "string", "description": "Name for a recurring review monitor, e.g. ace-hotel-weekly. Runs with the same name remember which reviews they already delivered and flag new ones with isNew.", "default": "" }, "onlyNew": { "title": "Emit only new reviews", "type": "boolean", "description": "With a monitor name, return (and bill) only reviews that earlier runs of the same monitor did not deliver. Reviews not delivered because of a spending limit come in the next run.", "default": false }, "maxPagesPerHotel": { "title": "Maximum source pages per hotel", "minimum": 1, "maximum": 500, "type": "integer", "description": "Safety ceiling on Booking.com review pages read per hotel (10 reviews per page), e.g. 100 pages = up to 1,000 reviews scanned. Selective filters may need more pages than reviews returned. With a reviewed date range and newest or oldest order, the Actor first jumps to that period and this is the number of pages it may read inside it.", "default": 100 }, "browserTimeoutSecs": { "title": "Browser timeout", "minimum": 20, "maximum": 120, "type": "integer", "description": "Maximum seconds to load a hotel page in the browser, e.g. 60. Half of it (at least 30 s) is used to wait for Booking.com's review session to start.", "default": 60 }, "graphqlTimeoutSecs": { "title": "Review request timeout", "minimum": 10, "maximum": 60, "type": "integer", "description": "Maximum seconds for each Booking.com review page request, e.g. 30. Raise it only on very slow connections.", "default": 30 }, "retries": { "title": "Retries", "minimum": 0, "maximum": 3, "type": "integer", "description": "How many times a hotel is retried in direct mode after a temporary browser or network failure, with growing pauses, e.g. 2. The proxy fallbacks get one try each.", "default": 2 }, "autoProxyFallback": { "title": "Automatic Apify Proxy fallback", "type": "boolean", "description": "Start direct for the lowest cost; if Booking.com blocks the session, retry through the Apify datacenter proxy (included in the price).", "default": true }, "residentialFallback": { "title": "Residential proxy fallback (paid add-on)", "type": "boolean", "description": "Last resort if Booking.com blocks both direct and datacenter access: retry the hotel once through a US residential proxy. Charged $0.10 per residential attempt (event 'residential-hotel'), before the attempt. Off by default.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional proxy settings. Leave disabled for direct-first mode with automatic datacenter fallback; residential groups are replaced by the included datacenter proxy (use the residential add-on above instead).", "default": { "useApifyProxy": false } } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }