{ "openapi": "3.0.1", "info": { "title": "Booking.com Hotel Scraper – Prices, Room Rates & Reviews", "description": "Scrape Booking.com hotel prices, room rates and availability via the mobile API. Full per-room rate table with itemised taxes and fees, family pricing by child age, guest reviews and property details — one actor, not four. Search by destination, GPS radius or hotel id. No API key needed.", "version": "1.0", "x-build-id": "SnVuzaa2ce7dZeJAK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/rl1987~booking-api-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-rl1987-booking-api-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/rl1987~booking-api-scraper/runs": { "post": { "operationId": "runs-sync-rl1987-booking-api-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/rl1987~booking-api-scraper/run-sync": { "post": { "operationId": "run-sync-rl1987-booking-api-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", "properties": { "mode": { "title": "What this run does", "enum": [ "search", "rooms", "reviews", "reviewScores", "surroundings", "details" ], "type": "string", "description": "Pick Search for the normal flow, or an enrichment mode to re-check properties you already have ids for without searching again.", "default": "search" }, "checkin": { "title": "Check-in", "type": "string", "description": "Check-in date, `YYYY-MM-DD` or a relative value like \"30 days\". Empty = 30 days from today.\n\n**Used by more than one mode:** a Search prices this stay, *Room pricing & availability* re-prices it, and *Guest reviews* uses it only when no `ufi` is given." }, "checkout": { "title": "Check-out", "type": "string", "description": "Departure date. Defaults to check-in + 1 night." }, "windowDays": { "title": "Flexible dates: search a window of days", "minimum": 1, "maximum": 60, "type": "integer", "description": "Ask \"any stay starting in the next N days\" instead of one fixed stay. Set this together with **Nights per stay** below.\n\nThe window starts today, or at **Check-in** if you set one. Each day in it is a separate search of its own, **billed separately** — a 30-day window costs roughly 30× a single-date run — so keep it as short as the question allows and set **Max accommodations**, which is a budget across the whole sweep, not per day.\n\nCapped at 60 days. Only applies to the *Search* and *Room pricing & availability* modes: the others return the same answer whatever the dates." }, "stayNights": { "title": "Flexible dates: nights per stay", "minimum": 1, "type": "integer", "description": "How long each stay in the window is. `1` asks for single nights — \"the cheapest single night in the next 30 days\". Ignored unless **Search a window of days** is set." }, "rooms": { "title": "Rooms", "minimum": 1, "type": "integer", "description": "Number of rooms to book for.", "default": 1 }, "adults": { "title": "Adults", "minimum": 1, "type": "integer", "description": "Number of adult guests.", "default": 2 }, "childrenAges": { "title": "Children ages", "type": "array", "description": "Ages of the children in the party, one per line (e.g. 5 then 9). Booking prices family stays by child age (free cots, kids-stay-free rules), so set this for correct prices and to surface family rooms.", "items": { "type": "string" } }, "currency": { "title": "Currency", "enum": [ "USD", "EUR", "GBP", "AUD", "CAD", "CHF", "CNY", "JPY", "INR", "BRL", "MXN", "SEK", "NOK", "DKK", "PLN", "AED", "SGD", "ZAR", "TRY", "RUB" ], "type": "string", "description": "Currency for displayed prices.", "default": "USD" }, "language": { "title": "Language / locale", "enum": [ "en-us", "en-gb", "de", "fr", "es", "it", "nl", "pt", "pt-br", "pl", "ru", "ja", "zh", "zh-tw", "ko", "ar", "tr", "sv", "da", "no", "fi" ], "type": "string", "description": "Locale for localized text (names, facilities, reviews).", "default": "en-us" }, "searchBy": { "title": "Search by (sub-mode)", "enum": [ "auto", "destination", "hotelIds", "cityId", "regionId", "point", "area" ], "type": "string", "description": "Pick how to find properties, or leave on Auto. Ignored unless this run is a Search.", "default": "auto" }, "search": { "title": "Search by: destination name", "type": "string", "description": "Place name (city, region, landmark) resolved via Booking's own autocomplete — the easiest way to start, e.g. \"Amsterdam\".\n\nAutocomplete matches what Booking has a destination for, which is not always what you would guess: \"Queens\" resolves to Queenstown in New Zealand, and \"Manhattan\", \"Newark\" and \"Long Island City\" resolve to nothing at all. The run logs what it resolved to — check it. For a metro area Booking has no destination for, use mode 5 (custom area) instead.\n\nNaming one specific hotel here also works: it is detected and fetched directly, the same as mode 2." }, "hotel_ids": { "title": "Search by: specific properties (Hotel IDs)", "type": "array", "description": "Scrape specific properties by numeric Booking ID, one per line, e.g. 10004. **Set this and every other sub-mode is ignored.** These ids are also what the enrichment modes work on, so the same list re-checks rooms, reviews, scores or nearby places without searching.\n\nThis must be the internal numeric id, not a URL slug or a property name. To find it, open the hotel's Booking.com page, view the page source and search for `hotelId`.\n\nUnlike a search, this always returns a row per id — including one saying why there is no price (sold out, minimum stay, closed, unknown id).", "items": { "type": "string" } }, "cityId": { "title": "Search by: City ID (a number, not a name)", "type": "integer", "description": "Exact numeric destination id (ufi), e.g. -2140479 for Amsterdam. **This field takes a number**: typing \"Amsterdam\" here is rejected — use mode 1 for a name.\n\nOnly useful if you already have the id from a previous run's output." }, "regionId": { "title": "Search by: Region ID (a number, not a name)", "type": "integer", "description": "Exact numeric region id. **This field takes a number**, not a region name — use mode 1 for a name. Only useful if you already have the id." }, "latitude": { "title": "Search by: latitude (point)", "type": "number", "description": "Sub-mode **Point and radius**: search outward from one GPS point, nearest first — \"within N km of this venue\" rather than \"in this city\". Latitude and Longitude are required together; Radius is optional." }, "longitude": { "title": "Longitude", "type": "number", "description": "Longitude paired with Latitude." }, "radius": { "title": "Search radius (km)", "type": "number", "description": "Only keep properties within this many kilometres of the point. **Applied after the results come back**, not by Booking — so a tight radius spends your Max accommodations budget on properties that are then discarded. Leave empty for nearest-first with no cut-off." }, "swLat": { "title": "Search by: bounding box — south-west latitude", "type": "string", "description": "Sub-mode **Bounding box**: sweep an arbitrary rectangle instead of a destination. Use it for ground Booking has no single destination for — New York's city destination holds ~520 properties, while a box over the same area also reaches Jersey City, Hoboken and North Bergen.\n\n**All four corners are required together.** A box costs far more requests per property than a destination search, so keep it tight and set Max accommodations.\n\n**Coverage reporting differs.** A destination search can say how complete it was (\"5,822 of 5,844 properties, 99.6%\") because Booking reports a total; a box cannot, so the log reports whether every cell was fully reached instead of a percentage." }, "swLon": { "title": "Bounding box — south-west longitude", "type": "string", "description": "West edge of the search rectangle." }, "neLat": { "title": "Bounding box — north-east latitude", "type": "string", "description": "North edge of the search rectangle." }, "neLon": { "title": "Bounding box — north-east longitude", "type": "string", "description": "East edge of the search rectangle." }, "deepSearch": { "title": "Deep search (auto-enables above 1,000 Max accommodations)", "type": "boolean", "description": "Booking's search stops returning new properties at roughly 1,000 per destination. With this on, the actor splits a large destination into geographic shards and merges the results, reaching several times more properties (measured: 1,104 -> 6,170 for Tokyo). Costs proportionally more requests, and each property is still returned - and billed - only once. Left unset, it turns on automatically when Maximum results is above 1,000." }, "accommodationTypes": { "title": "Accommodation types", "type": "array", "description": "Limit results to these property types. Leave empty for all types. Pick from the list here; via the API this field takes Booking’s numeric type ids as strings (e.g. \"201\" for Apartments). An id sent as a number, or a type name, is rejected before the run starts. To pass names case-insensitively (\"Apartments\", \"villa\"), or ids as numbers, use the snake_case spelling \"accommodation_types\" instead. See the README for the full id → name table.", "items": { "type": "string", "enum": [ "201", "203", "204", "205", "206", "208", "209", "210", "212", "213", "214", "215", "216", "218", "219", "220", "221", "222", "223", "224", "225", "226", "227", "228" ], "enumTitles": [ "Apartments", "Hostels", "Hotels", "Motels", "Resorts", "Bed and Breakfasts", "Ryokans", "Farm Stays", "Resort Villages", "Villas", "Campgrounds", "Boats", "Guesthouses", "Inns", "Condo Hotels", "Vacation Homes", "Lodges", "Homestays", "Country Houses", "Luxury tents", "Capsule Hotels", "Love Hotels", "Riads", "Chalets" ] }, "default": [] }, "minReviewScore": { "title": "Minimum review score", "minimum": 1, "maximum": 10, "type": "integer", "description": "Only return properties with at least this guest review score (1–10). Applied client-side." }, "minPrice": { "title": "Minimum price (per stay)", "minimum": 0, "type": "integer", "description": "Only return properties at or above this total stay price, in the selected currency. Applied client-side." }, "maxPrice": { "title": "Maximum price (per stay)", "minimum": 0, "type": "integer", "description": "Only return properties at or below this total stay price, in the selected currency. Applied client-side." }, "sortBy": { "title": "Sort by", "enum": [ "none", "price", "review_score" ], "type": "string", "description": "Order of the returned accommodations.", "default": "none" }, "sortDirection": { "title": "Sort direction (needs Sort by)", "enum": [ "ascending", "descending" ], "type": "string", "description": "Applies only when \"Sort by\" is set to Price or Review score.", "default": "ascending" }, "includeRooms": { "title": "Include rooms & products", "type": "boolean", "description": "Add both room sections: the per-rate `products` list (board, cancellation, deals, price) AND the distinct room-type `rooms` list (name, occupancy, availability, lowest price). Costs one extra request per property in search mode.", "default": false }, "onlyFittingProducts": { "title": "Only rates that fit the party (needs Include rooms)", "type": "boolean", "description": "When rooms are included, keep only rates Booking would actually sell to your party (its `is_block_fit` flag) in `products`, and compute `rooms[].minPrice` / `productCount` from those. Turn off to get every rate of every occupancy (each still carries `fitsParty`).", "default": true }, "includeDetails": { "title": "Include static details", "type": "boolean", "description": "Add a `details` object per property: name, type, star rating, review score/count, location, main photos, named facilities, languages spoken and address. Costs one extra request per property in search mode.", "default": false }, "includeSurroundings": { "title": "Include nearby places", "type": "boolean", "description": "Add nearby landmarks, public transport, dining and airports with distances, under \"details.surroundings\". Costs one extra API request per property and is billed as its own \"Nearby places\" event. Off by default: until 1.0.50 this was fetched automatically with \"Include details\" and not charged.", "default": false }, "includeReviews": { "title": "Include reviews", "type": "boolean", "description": "Add a `reviews` array per property (author, score, title, pros/cons, date). Costs one request per 10 reviews per property.", "default": false }, "maxReviews": { "title": "Max reviews per property (needs Include reviews)", "minimum": 1, "type": "integer", "description": "How many reviews to fetch per property (only when \"Include reviews\" is on). Capped by the property's total review count.", "default": 10 }, "includeReviewScores": { "title": "Include review scores & summary", "type": "boolean", "description": "Add per-category review subscores (staff, cleanliness, location, value, comfort, facilities, wifi) and the aggregated review summary, under \"reviewSubscores\" and \"reviewSummary\". Costs one extra API request per property regardless of how many reviews you fetch, and is billed as its own \"Review scores\" event. Off by default: until 1.0.50 this rode along free with \"Include reviews\".", "default": false }, "includeExtraCharges": { "title": "Include extra-charge breakdown", "type": "boolean", "description": "Add the `extra_charges` price breakdown (taxes/fees) to each result and product.", "default": true }, "hotelIdsRooms": { "title": "Hotel IDs", "type": "array", "description": "The properties to run **Room pricing & availability** on, one numeric Booking ID per line, e.g. 10004. This must be the internal numeric id, not a URL slug or a property name: open the hotel's Booking.com page, view source and search for `hotelId`.", "items": { "type": "string" } }, "roomsOnlyFitting": { "title": "Only rates that fit the party", "type": "boolean", "description": "Keep only rates Booking would actually sell to the party in **Stay details** below. Turn off for every rate of every occupancy.", "default": true }, "roomsExtraCharges": { "title": "Itemise taxes and fees", "type": "boolean", "description": "Break each tax and fee out of the rate instead of a blended total.", "default": true }, "hotelIdsReviews": { "title": "Hotel IDs", "type": "array", "description": "The properties to run **Guest reviews** on, one numeric Booking ID per line, e.g. 10004. This must be the internal numeric id, not a URL slug or a property name: open the hotel's Booking.com page, view source and search for `hotelId`.", "items": { "type": "string" } }, "ufi": { "title": "Destination ufi (reviews mode only)", "type": "string", "description": "Booking's reviews endpoint refuses to return anything without the destination's `ufi`, so the reviews mode needs one. Take it from an earlier search run's output and paste it here to skip a lookup; leave it empty and one extra request per property derives it. A ufi identifies a destination, not a property, so one value covers every property in that destination." }, "countryCode": { "title": "Country code (reviews mode only)", "type": "string", "description": "ISO 2-letter code for the property's country, paired with the ufi above. Optional — Booking tolerates it being empty." }, "reviewsMax": { "title": "Max reviews per property", "minimum": 1, "type": "integer", "description": "Capped by the property's own review count.", "default": 10 }, "hotelIdsScores": { "title": "Hotel IDs", "type": "array", "description": "The properties to run **Review score summary** on, one numeric Booking ID per line, e.g. 10004. This must be the internal numeric id, not a URL slug or a property name: open the hotel's Booking.com page, view source and search for `hotelId`.", "items": { "type": "string" } }, "hotelIdsSurroundings": { "title": "Hotel IDs", "type": "array", "description": "The properties to run **Nearby places** on, one numeric Booking ID per line, e.g. 10004. This must be the internal numeric id, not a URL slug or a property name: open the hotel's Booking.com page, view source and search for `hotelId`.", "items": { "type": "string" } }, "hotelIdsDetails": { "title": "Hotel IDs", "type": "array", "description": "The properties to run **Static property details** on, one numeric Booking ID per line, e.g. 10004. This must be the internal numeric id, not a URL slug or a property name: open the hotel's Booking.com page, view source and search for `hotelId`.", "items": { "type": "string" } }, "outputFields": { "title": "Output fields (leave empty for the full record)", "type": "array", "description": "Leave empty for the full record. Selecting Nearby places without Static details keeps a `details` object holding only `surroundings`.", "items": { "type": "string", "enum": [ "price", "availability", "property", "rooms", "details", "reviews", "reviewScores", "surroundings" ], "enumTitles": [ "Pricing", "Availability", "Property facts", "Rooms & rates", "Static details", "Guest reviews", "Review scores & subscores", "Nearby places" ] }, "default": [] }, "maxItems": { "title": "Max accommodations", "minimum": 1, "type": "integer", "description": "Maximum number of accommodations to return.\n\nAbove 1,000 this turns Deep search on by itself, because Booking's search stops returning new properties at roughly that point.", "default": 100 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum parallel requests for product/detail fetches.", "default": 10 }, "units": { "title": "Units", "enum": [ "metric", "imperial" ], "type": "string", "description": "Unit system for distances - distance from the city centre and the nearby landmarks, transport and airports returned with includeDetails. Booking localises distances by language (metres for German, feet for US English); this normalises them to the system you pick.", "default": "metric" }, "bookerCountry": { "title": "Booker country code", "type": "string", "description": "ISO 2-letter country of the booker. Affects some localized pricing." }, "exportExcel": { "title": "Export an Excel workbook (.xlsx)", "type": "boolean", "description": "Also write an Excel workbook to this run's storage, with a sheet per section (Properties, and Rates/Rooms/Reviews when those are included) instead of nested JSON in a cell. Download it from the run's **Storage** tab. Does not change the dataset or what you are charged.\n\n**In enrichment modes only that mode's sheet fills**: Rates and Rooms for *Room pricing*, Reviews for *Guest reviews*. The Properties sheet holds the id alone, and nearby places, review scores and static details have no sheet — they reach you through the dataset instead.", "default": false }, "excelFileName": { "title": "Excel file name", "type": "string", "description": "Name for the workbook in the key-value store.", "default": "OUTPUT.xlsx" }, "exportKml": { "title": "Export a map file (.kml)", "type": "boolean", "description": "Also write a KML file with one placemark per property, ready to open in Google Earth, Google My Maps or QGIS. Each pin carries the price, review score, address and a link to the property, plus a photo when **Include details** is also on. Properties without coordinates are skipped.\n\n**Only produces pins in Search mode.** The enrichment modes return rows without coordinates, so a map built from them has 0 placemarks. For a map of properties you already have ids for, use Search with the *Specific properties* sub-mode.", "default": false }, "kmlFileName": { "title": "KML file name", "type": "string", "description": "Name for the KML file in the key-value store.", "default": "OUTPUT.kml" }, "kmlColorBy": { "title": "Colour map pins by", "enum": [ "none", "price", "review_score" ], "type": "string", "description": "Shade the placemarks so the map reads at a glance. **Price** uses this run's own quartiles (cheapest green, dearest red); **review score** uses fixed bands (9+ green, 8-9 amber, 7-8 orange, below 7 red).", "default": "none" }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings. Apify Proxy recommended.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } }