{ "openapi": "3.0.1", "info": { "title": "Agoda Reviews Scraper", "description": "Scrape Agoda hotel guest reviews by hotel URL or ID — rating, title, text, pros/cons, reviewer profile, hotel response, and dates. HTTP-only, MCP-ready.", "version": "1.0", "x-build-id": "4ovgtJNtVMlYT5zbS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~agoda-reviews-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-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/khadinakbar~agoda-reviews-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-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/khadinakbar~agoda-reviews-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-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": { "hotelUrls": { "title": "Agoda hotel URLs", "type": "array", "description": "Agoda hotel page URLs to scrape reviews from (e.g. 'https://www.agoda.com/the-berkeley-hotel-pratunam/hotel/bangkok-th.html'). The actor auto-extracts the numeric hotelId from each page. Accepts any Agoda locale/subpath. NOT a search or city URL — pass one URL per hotel. Leave empty if you supply hotelIds instead.", "items": { "type": "string" } }, "hotelIds": { "title": "Agoda hotel IDs", "type": "array", "description": "Numeric Agoda hotel IDs to scrape directly, skipping the page fetch (e.g. '461790'). Find the ID in the hotel URL query string or page source. Faster than hotelUrls because no HTML page is downloaded. NOT the property name or a booking ID — must be the numeric hotelId.", "items": { "type": "string" } }, "maxReviewsPerHotel": { "title": "Max reviews per hotel", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of reviews to collect per hotel before stopping. Controls run cost since each review is a billable event. Defaults to 100. Set 0 or a very high number to attempt all available reviews (large hotels have tens of thousands). Applies per hotel, not across the whole run.", "default": 100 }, "sortBy": { "title": "Sort order", "enum": [ "most_recent", "most_helpful", "highest_rated", "lowest_rated" ], "type": "string", "description": "Order in which Agoda returns reviews. 'most_recent' pulls newest first (best for monitoring). 'most_helpful' pulls Agoda's top-voted reviews. 'highest_rated'/'lowest_rated' sort by score. Defaults to 'most_recent'. Does not change which reviews exist, only their order and thus which ones you get first under a maxReviewsPerHotel cap.", "default": "most_recent" }, "includeAllProviders": { "title": "Include all review providers", "type": "boolean", "description": "Agoda aggregates reviews from Agoda plus partner sources (e.g. Booking.com). When true, the actor iterates every available provider for each hotel to maximize coverage. When false (default) it scrapes only Agoda's own reviews, which are the largest and most consistent set. Turn on for maximum volume, off for cleaner Agoda-native data.", "default": false }, "onlyReviewsWithText": { "title": "Only reviews with text", "type": "boolean", "description": "When true, skips rating-only entries that have no written comment, positives, or negatives. Useful for sentiment analysis where empty reviews add noise. When false (default) every review is returned, including score-only ones. Filtering happens after fetch, so it does not reduce billing on the fetched page.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings. Defaults to Apify Residential proxies, which are required — Agoda rate-limits datacenter IPs. Leave as default unless you have a specific reason to change it.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }