{ "openapi": "3.0.1", "info": { "title": "Agoda Reviews Scraper", "description": "Agoda reviews of any hotel, by URL, ID, name or a whole city: Agoda and Booking.com reviews with text, rating, date, traveler type, country and hotel reply. Filter by traveler type, language, rating and date; monitor new reviews. Export JSON, CSV or Excel.", "version": "0.1", "x-build-id": "JXd8dwxcc7gnA5V0A" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nice_dev~agoda-reviews-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nice_dev-agoda-reviews-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/nice_dev~agoda-reviews-scraper/runs": { "post": { "operationId": "runs-sync-nice_dev-agoda-reviews-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/nice_dev~agoda-reviews-scraper/run-sync": { "post": { "operationId": "run-sync-nice_dev-agoda-reviews-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": { "startUrls": { "title": "Hotel URLs", "maxItems": 1000, "type": "array", "description": "Agoda hotel pages copied from the address bar (`https://www.agoda.com//hotel/.html`), in any site language. One hotel per URL: its Agoda and Booking.com reviews are read, up to **Max reviews per hotel** (100 by default). Max 1 000 URLs. With no hotel, ID, name or city at all, the Actor reads the reviews of an example hotel (at most 20) instead of stopping.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "propertyIds": { "title": "Hotel IDs", "maxItems": 5000, "uniqueItems": true, "type": "array", "description": "Agoda numeric hotel ids (e.g. `335650`, the number after `hotel_id=` or in the page data), when you already have them: no search, one hotel per id. Added to the hotel URLs.", "default": [], "items": { "type": "string" } }, "hotelNames": { "title": "Hotel names", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Hotels named as you would type them on Agoda (e.g. `Park Hyatt Tokyo`): each name is looked up in Agoda's own suggestions before the run. The hotel of exactly that name wins, else the first one Agoda proposes (the log says which one). Added to the hotel URLs.", "default": [], "items": { "type": "string" } }, "locations": { "title": "Cities (reviews of every hotel)", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Cities as typed on the site (e.g. `Paris`, `Bangkok`, `Bali`): the Actor reads the reviews of the first **Max hotels per city** hotels of each city, in the order of **Sort hotels by**. The city of exactly that name wins; a district, an airport or a landmark is refused with the City ID of its city. Added to the hotels above.", "default": [], "items": { "type": "string" } }, "cityIds": { "title": "City IDs", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Agoda numeric city ids (e.g. `15470` for Paris), when you already know them: no name resolution, no ambiguity. Same use as **Cities**.", "default": [], "items": { "type": "string" } }, "maxHotelsPerCity": { "title": "Max hotels per city", "minimum": 1, "maximum": 5000, "type": "integer", "description": "How many hotels of each city to read the reviews of, taken in the order of **Sort hotels by** after the hotel filters below. A big city holds about 4 500 hotels: keep it small, and use **Max reviews** to bound the whole run.", "default": 10 }, "sortBy": { "title": "Sort hotels by", "enum": [ "recommended", "review_high_to_low", "review_low_to_high", "newest", "recent", "most_recent", "mostHelpful" ], "type": "string", "description": "Order of the hotels of a city. `recommended` is the only order Agoda keeps stable between two calls; the others may repeat or skip hotels, which the Actor absorbs by de-duplicating. Not used for hotels given by URL, ID or name. The last four entries are the order of REVIEWS that other Agoda review scrapers call `sortBy`: they are read as **Reviews order**.", "default": "recommended" }, "minStars": { "title": "Minimum star rating", "minimum": 0, "maximum": 5, "type": "integer", "description": "Hotel filter for the hotels of a city: keep hotels with at least this many stars (1-5). 0 = no filter. Asked from the site, so filtered hotels are never read.", "default": 0 }, "maxStars": { "title": "Maximum star rating", "minimum": 0, "maximum": 5, "type": "integer", "description": "Hotel filter for the hotels of a city: keep hotels with at most this many stars. 0 = no filter.", "default": 0 }, "minHotelRating": { "title": "Minimum hotel rating", "minimum": 0, "maximum": 10, "type": "number", "description": "Hotel filter for the hotels of a city: keep hotels whose guest score is at least this (Agoda scores out of 10). 0 = no filter. Hotels without any review are dropped when this is set. For a filter on the reviews themselves, see **Minimum review rating**.", "default": 0 }, "minReviewCount": { "title": "Minimum number of reviews of the hotel", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Hotel filter for the hotels of a city: keep hotels with at least this many reviews. 0 = no filter.", "default": 0 }, "propertyTypes": { "title": "Property types", "maxItems": 30, "uniqueItems": true, "type": "array", "description": "Hotel filter for the hotels of a city, asked from Agoda: `Hotel`, `Apartment`, `Serviced apartment`, `Resort`, `Villa`, `Hostel`, `Guest House`, `Bed & Breakfast`, `Homestay`, `Entire House`, `Motel`, `Inn`, `Ryokan`, `Capsule hotel`… — or the number of the type on the site. Hotels given by URL, ID or name are not filtered by type. Empty = every type.", "default": [], "items": { "type": "string" } }, "excludePropertyIds": { "title": "Exclude hotel IDs", "maxItems": 5000, "uniqueItems": true, "type": "array", "description": "Agoda hotel ids to skip, even when they match a city (e.g. your own hotels).", "default": [], "items": { "type": "string" } }, "maxReviewsPerHotel": { "title": "Max reviews per hotel", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Cap on the reviews saved for each hotel, Agoda and Booking.com together: the first ones in Agoda's order (the language of the site first, then the other languages; see **Reviews order**). 0 = every review of the hotel (The Magani, Bali: 1 506 reviews, all read) — set **Max reviews** to 0 too: it caps the whole run (1 000 by default). A request brings up to 100 reviews of each source, so 100 reviews cost about one request per hotel.", "default": 100 }, "maxItems": { "title": "Max reviews", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of reviews saved for the whole run, all hotels together. 0 = no limit. It also stops a run whose hotels have more reviews than this (the log and the last message say so): set it to 0 to read every review of every hotel. Use it to bound the cost of a city or a long list of hotels.", "default": 1000 }, "reviewsSort": { "title": "Reviews order", "enum": [ "newest", "highest_rating", "lowest_rating", "most_helpful", "recent", "most_recent", "mostHelpful" ], "type": "string", "description": "Order of the reviews read. Agoda lists the reviews in the language of the site (and the ones it translated) first, then each other language apart, each group in this order. With a cap, the first ones in that order are kept: not always the most recent (or best) of the whole hotel. Most recent first lets a date filter skip the older reviews unread.", "default": "newest" }, "reviewProviders": { "title": "Review sources", "uniqueItems": true, "type": "array", "description": "Which sources to keep: the reviews written on Agoda, the ones Booking.com publishes on Agoda, or both. Both come in the same request, at no extra cost. Untick one to keep only the other.", "items": { "type": "string", "enum": [ "agoda", "booking" ], "enumTitles": [ "Agoda", "Booking.com" ] }, "default": [ "agoda", "booking" ] }, "travelerType": { "title": "Traveler type", "enum": [ "all", "business", "couples", "solo", "families_young_children", "families_teens", "groups" ], "type": "string", "description": "Keep only the reviews of one type of traveler. Done by Agoda itself: the other reviews are never read, so they cost nothing and the cap counts only the ones you want.", "default": "all" }, "reviewLanguages": { "title": "Review languages", "maxItems": 40, "uniqueItems": true, "type": "array", "description": "Keep only the reviews written in these languages: the English name (`French`, `Japanese`, `English`), the name Agoda shows (`Français`, `日本語`, `Русский`), an ISO code (`fr`, `ja`, `zh-tw`) or Agoda's own number; case and accents are ignored. `English` covers English, UK, Australian and New Zealand reviews. A language Agoda does not list is refused before the run, with the names accepted. Done by Agoda itself: the other reviews are never read, so they cost nothing. A language a hotel has no review in gives 0 review for that hotel, not an error. Empty = every language.", "default": [], "items": { "type": "string" } }, "reviewsMinRating": { "title": "Minimum review rating", "minimum": 0, "maximum": 10, "type": "number", "description": "Keep only the reviews scored at least this (out of 10). 0 = every review. With **Highest rating first**, once a lower review is met the lower ones are skipped unread and not charged (Agoda sorts each language apart: the hotel is still read to its end). Reviews read then dropped by this filter are charged a small filter fee (see Pricing).", "default": 0 }, "reviewsMaxRating": { "title": "Maximum review rating", "minimum": 0, "maximum": 10, "type": "number", "description": "Keep only the reviews scored at most this (out of 10). 0 = every review. Set it low to collect complaints only; with **Lowest rating first**, once a higher review is met the higher ones are skipped unread and not charged (Agoda sorts each language apart: the hotel is still read to its end). Reviews read then dropped by this filter are charged a small filter fee (see Pricing).", "default": 0 }, "reviewsAfter": { "title": "Reviews after", "type": "string", "description": "Keep only the reviews written on or after this date: `2026-01-01`, or a period before now such as `7 days`, `3 months`, `1 year`. With **Most recent first**, once an older review is met the older ones are skipped unread and not charged (Agoda sorts each language apart: the hotel is still read to its end). Reviews read then dropped by this filter are charged a small filter fee (see Pricing)." }, "reviewsBefore": { "title": "Reviews before", "type": "string", "description": "Keep only the reviews written on or before this date (the whole day is included), or a period before now such as `1 month`. Reviews read then dropped by this filter are charged a small filter fee (see Pricing). With **Only new reviews** and a period, a review still too recent is read again, with that fee, at each run until the period reaches it." }, "keywords": { "title": "Keywords", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Keep only the reviews whose text, title, liked part or disliked part contains at least one of these words (whole words, case and accents ignored): `breakfast`, `bed bugs`, `noise`. Agoda has no keyword search, so the Actor reads the reviews and drops the others: each one dropped is charged a small filter fee (see Pricing). Empty = no filter.", "default": [], "items": { "type": "string" } }, "withResponseOnly": { "title": "Only reviews with a hotel reply", "type": "boolean", "description": "Keep only the reviews the hotel answered (`responseText` filled). Reviews read then dropped are charged a small filter fee (see Pricing).", "default": false }, "withPhotosOnly": { "title": "Reviews with photos only", "type": "boolean", "description": "Keep only the reviews where the guest added at least one photo (`reviewImages` not empty). Agoda has no such filter, so the Actor reads the reviews and drops the others: each one dropped is charged a small filter fee (see Pricing).", "default": false }, "seasons": { "title": "Stay season", "maxItems": 4, "uniqueItems": true, "type": "array", "description": "Keep only the reviews of a stay in these times of the year, the same four as the **Time of the year** filter on Agoda: Mar - May, Jun - Aug, Sep - Nov, Dec - Feb. Judged on the month of the stay date; a review without a readable stay date is dropped. Booking.com reviews have no stay date: with this filter, only Agoda reviews are read. Agoda gives no way to ask for it, so the Actor reads the reviews and drops the others: each one dropped is charged a small filter fee (see Pricing). Empty = every season.", "items": { "type": "string", "enum": [ "mar_to_may", "jun_to_aug", "sep_to_nov", "dec_to_feb" ], "enumTitles": [ "Mar - May", "Jun - Aug", "Sep - Nov", "Dec - Feb" ] }, "default": [] }, "language": { "title": "Site language", "pattern": "^([a-zA-Z]{2}-[a-zA-Z]{2}|all)$", "maxLength": 5, "type": "string", "description": "Agoda locale (`en-us`, `fr-fr`, `de-de`, `es-es`, `ja-jp`, `th-th`, `zh-cn`…). Agoda translates some reviews into it: the row then holds the translation in `reviewComments` and the original in `originalText` / `originalTitle`. `all` (the value some other scrapers use) means the default, `en-us`. To keep one review language, use **Review languages**.", "default": "en-us" }, "includeHotelDetails": { "title": "Add hotel details to each review", "type": "boolean", "description": "Add the hotel's address, GPS position, star rating and accommodation type (and, for a hotel given by URL, ID or name, its city and country) to every review row of that hotel. One profile read per hotel, charged apart once per hotel, not per review (see Pricing). Off = the name, city (for a hotel found in a city), overall score, scores per criterion and counts of the hotel are on each row anyway, for free.", "default": false }, "onlyNew": { "title": "Only new reviews", "type": "boolean", "description": "Skip the reviews that a previous run (same **Memory key**) already delivered, or already checked and dropped by your filters: they are not saved or charged as reviews again. On the first page of a hotel they cost nothing; read again on a later page, each costs one filter check (once per run). With **Max reviews per hotel** above 0, a later run reads no further than where that cap stopped the earlier one (a run right after it returns nothing; 100 = usually the first page only); 0 catches every new review, and reads every page again. First run = everything is new.", "default": false }, "stateKey": { "title": "Memory key", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "maxLength": 64, "type": "string", "description": "Name of the memory used by **Only new reviews**. Give each schedule / task its own key (e.g. `paris-hotels`) so that they do not share their memory. Changing a filter (score, dates, keywords, replies)? Use a new key, or tick **Reset the memory** once: the reviews the old filter dropped are remembered and would not come back. Letters, digits, `-` and `_`.", "default": "default" }, "resetState": { "title": "Reset the memory", "type": "boolean", "description": "Forget everything remembered under this **Memory key** before the run: this run returns (and charges) every review again. Untick it afterwards.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy or your own proxies. Keep the default: it is included in the price. The residential Apify proxy is not available in this Actor.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum number of requests processed in parallel. Together with **Min delay between requests**, it sets how fast the run goes.", "default": 4 }, "minRequestIntervalMs": { "title": "Min delay between requests", "minimum": 0, "maximum": 60000, "type": "integer", "description": "Minimum time between two requests leaving the Actor, in milliseconds. Lower it only with your own proxies.", "default": 1000 }, "maxRequestsPerMinute": { "title": "Max requests per minute", "minimum": 6, "maximum": 600, "type": "integer", "description": "Upper bound on the request rate for the whole run, on top of **Min delay between requests**.", "default": 60 }, "maxRequestRetries": { "title": "Max request retries", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retries per request before it is marked as failed.", "default": 5 }, "debugLog": { "title": "Debug log", "type": "boolean", "description": "Include debug messages in the run log.", "default": false }, "hotelUrl": { "title": "Hotel URL (other scrapers' name)", "maxLength": 2000, "type": "string", "description": "Name used by other Agoda review scrapers, accepted so that their input runs here unchanged; use **Hotel URLs**." }, "cutoffDate": { "title": "Cut-off date (other scrapers' name)", "maxLength": 40, "type": "string", "description": "Name used by other Agoda review scrapers, accepted so that their input runs here unchanged; use **Reviews after**." }, "reviewsStartDate": { "title": "Reviews start date (other scrapers' name)", "maxLength": 40, "type": "string", "description": "Name used by other Agoda review scrapers, accepted so that their input runs here unchanged; use **Reviews after**." }, "fromDate": { "title": "From date (other scrapers' name)", "maxLength": 40, "type": "string", "description": "Name used by other Agoda review scrapers, accepted so that their input runs here unchanged; use **Reviews after**." }, "toDate": { "title": "To date (other scrapers' name)", "maxLength": 40, "type": "string", "description": "Name used by other Agoda review scrapers, accepted so that their input runs here unchanged; use **Reviews before**." }, "aggregateRatings": { "title": "Aggregate ratings (other scrapers' name)", "type": "boolean", "description": "Name used by other Agoda review scrapers, accepted so that their input runs here unchanged. It changes nothing: the scores of the hotel (overall, per source and per criterion) are on every row." }, "maxItemsPerSearch": { "title": "Max reviews per hotel (other scrapers' name)", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Name used by other Agoda review scrapers, accepted so that their input runs here unchanged; use **Max reviews per hotel**. 0 = every review of the hotel." }, "includeOtherSites": { "title": "Include Booking.com reviews (other scrapers' name)", "type": "boolean", "description": "Name used by other Agoda review scrapers, accepted so that their input runs here unchanged; use **Review sources**. false = Agoda reviews only, true = Agoda and Booking.com." }, "ratingFilter": { "title": "Rating filter (other scrapers' name)", "maxLength": 200, "type": "string", "description": "Name used by other Agoda review scrapers, accepted so that their input runs here unchanged; use **Minimum review rating** and **Maximum review rating**. A minimum score such as `8`, or score bands separated by commas (`exceptional`, `excellent`, `very_good`, `good`, `below_expectation`)." } } }, "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 } } } } } } } } } }