{ "openapi": "3.0.1", "info": { "title": "Agoda Prices Scraper — Hotel Rates & Availability by Date", "description": "Agoda hotel prices and availability for destinations or hotels by URL, id or name. One row per hotel: nightly and total price, taxes, free cancellation, rooms left, stars, guest score, sold out. Price calendar: cheapest dates. Filters before billing: max price, stars, guest score. ราคาโรงแรม, ホテル料金", "version": "1.1", "x-build-id": "zqWiIFSdPxjXTkDaP" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/kestrel~agoda-prices-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-kestrel-agoda-prices-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/kestrel~agoda-prices-scraper/runs": { "post": { "operationId": "runs-sync-kestrel-agoda-prices-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/kestrel~agoda-prices-scraper/run-sync": { "post": { "operationId": "run-sync-kestrel-agoda-prices-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": { "locationQueries": { "title": "Destinations", "type": "array", "description": "Cities or areas as typed into Agoda, e.g. [\"Bangkok\"], [\"Lisbon\", \"Bali\"], an Agoda city id (\"16364\") or an agoda.com search URL. Each is resolved through Agoda's own autocomplete (best match wins; add the country for ambiguous names) and becomes one search returning up to maxHotelsPerQuery priced properties in sortBy order. An unmatched place is a free status row, nothing charged. Empty = price only the hotels named below. Use for \"hotel prices in Bangkok next month\".", "default": [], "items": { "type": "string" } }, "hotelIds": { "title": "Hotel ids", "type": "array", "description": "Agoda numeric property ids, e.g. [\"63820\", \"6988894\"]: the hotel_id column of an earlier run. The fastest way to price a known list every day (a comp set, a portfolio): one small request per hotel, no page read. An unknown id is a free status row (not_found). A hotel given twice, or reached by a destination search too, is delivered and billed once. Add calendarDays for each hotel's cheapest dates.", "default": [], "items": { "type": "string" } }, "hotelNames": { "title": "Hotel names", "type": "array", "description": "Property names, e.g. [\"Tivoli Avenida Liberdade Lisbon\", \"Mandarin Oriental Bangkok\"]: add the city. Resolved through Agoda's own autocomplete; the best match is priced on its own for the stay, and the free status row carries hotel_name and hotel_id, so check it. A name that matches nothing costs nothing. sortBy and maxHotelsPerQuery do not apply to named hotels; the filters do. Use for \"what does hotel X cost on these dates\".", "default": [], "items": { "type": "string" } }, "startUrls": { "title": "Agoda URLs", "type": "array", "description": "Agoda URLs, e.g. [\"https://www.agoda.com/tivoli-avenida-liberdade/hotel/lisbon-pt.html\"]: a property page is priced on its own (the page is read once to find its id); a search URL (agoda.com/search?city=…) is treated like a destination. URLs from other sites are refused before anything is charged. Prefer hotelIds when you have them.", "default": [], "items": { "type": "string" } }, "checkIn": { "title": "Check-in", "type": "string", "description": "Check-in date: \"2026-11-20\" (YYYY-MM-DD) or relative to the day the run starts: \"30 days\" (default), \"6 weeks\", \"tomorrow\". Use relative dates for scheduled runs (\"track prices daily\"): the input never goes stale. Check-out = checkIn + nights. A past date is refused before anything is charged. The price calendar (calendarDays) starts here too.", "default": "30 days" }, "nights": { "title": "Nights", "minimum": 1, "maximum": 30, "type": "integer", "description": "Length of stay, 1 to 30, e.g. 2 (default 1). price_total and price_total_with_taxes cover the whole stay for all rooms; price_nightly is per room per night.", "default": 1 }, "adults": { "title": "Adults", "minimum": 1, "maximum": 9, "type": "integer", "description": "Adults per booking, 1 to 9, e.g. 2 (default 2). Agoda prices the cheapest room that fits everyone; the price calendar is read at this adult count.", "default": 2 }, "children": { "title": "Children", "minimum": 0, "maximum": 9, "type": "integer", "description": "Children per booking, 0 to 9, e.g. 1 (default 0). Give their ages in childAges for exact child rates.", "default": 0 }, "childAges": { "title": "Child ages", "type": "array", "description": "One age per child, 0 to 17, in order, e.g. [\"5\", \"9\"] for two children aged 5 and 9. Empty (default) = no children. Give one age for each child counted in children.", "default": [], "items": { "type": "string" } }, "rooms": { "title": "Rooms", "minimum": 1, "maximum": 9, "type": "integer", "description": "Rooms per booking, 1 to 9, e.g. 1 (default 1). Nightly prices are per room; totals cover all rooms for the stay.", "default": 1 }, "currency": { "title": "Currency", "type": "string", "description": "ISO 4217 code for every price, e.g. \"THB\" (default \"USD\"): USD, EUR, GBP, THB, JPY, SGD, AUD, … converted at Agoda's own rate. When the user names no currency, pass the destination's (\"THB\" for Bangkok).", "default": "USD" }, "maxHotelsPerQuery": { "title": "Max hotels per destination", "minimum": 0, "maximum": 2000, "type": "integer", "description": "Priced properties per destination search, e.g. 100 (default 45 = one Agoda page). The main cost control: at most maxHotelsPerQuery × $0.004 per destination. Taken in sortBy order; the filters then drop rows, so 100 asked with maxPrice set can deliver fewer. 0 = every property Agoda lists for the stay, up to 40 pages (about 1,800 properties, up to $7.20 for a capital); values above that end at the same 40-page limit. The rank column is the position in that order. Not applied to named hotels.", "default": 45 }, "sortBy": { "title": "Sort destination results", "enum": [ "best_match", "price_low", "guest_rating", "secret_deals" ], "type": "string", "description": "Agoda's own order for destination searches: \"best_match\" (default, Agoda's ranking), \"price_low\" (cheapest first; Agoda only sorts price ascending), \"guest_rating\" (highest score first), \"secret_deals\". Use \"price_low\" with maxHotelsPerQuery for \"the 20 cheapest hotels in Bangkok\". The rank and sort columns record it. Ignored for named hotels.", "default": "best_match" }, "maxPrice": { "title": "Max nightly price", "minimum": 0, "type": "number", "description": "Highest nightly price in `currency`, e.g. 80. 0 (default) = no cap. Keeps hotels whose price_nightly (per room per night, before taxes: Agoda's displayed price) is at or under it. Dropped hotels are never delivered or billed: a daily \"anything under 80\" alert costs nothing on days without a match. Applies to destination searches and named hotels. Use for \"hotels under 80 USD a night\".", "default": 0 }, "minStars": { "title": "Min star rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Lowest star rating to keep, 0 to 5, e.g. 4 (= 4-star and 5-star properties). 0 (default) = any. Applied by the actor before billing, so dropped properties are free. Unrated properties (many apartments, hostels and Agoda Homes) have no stars and are dropped when this is set: use minReviewScore for those instead.", "default": 0 }, "minReviewScore": { "title": "Min guest score", "minimum": 0, "maximum": 10, "type": "number", "description": "Lowest guest review score to keep, 0 to 10, e.g. 8 (default 0 = any). Compared with review_score, Agoda's combined score across the sources it aggregates; unreviewed properties are dropped when this is set. Applied before billing. Use for \"well-rated hotels only\" or to rank hostels and apartments that have no stars.", "default": 0 }, "freeCancellationOnly": { "title": "Free cancellation only", "type": "boolean", "description": "false (default) = every priced hotel, with free_cancellation true or false on each row. true = keep only hotels whose cheapest rate is free to cancel (cancellation = FreeCancellation); the rest are dropped free of charge. Use for \"refundable hotels only\".", "default": false }, "calendarDays": { "title": "Price calendar days (properties only)", "minimum": 0, "maximum": 60, "type": "integer", "description": "0 (default) = no calendar. N = for each NAMED hotel (hotelIds, hotelNames, startUrls property pages; not destination searches) also price N check-in dates from checkIn, up to 60, one live search per date: one calendar row per date with a price, at your nights and adults, with price_nightly, price_total, rank_in_window (1 = cheapest) and Agoda's Low/Normal/High trend word where it has one (null on most dates). $0.002 per priced date; dates without a price are skipped free. Use for \"when is hotel X cheapest\" (20 hotels × 60 days ≤ $2.40).", "default": 0 }, "includeSoldOut": { "title": "Include sold-out properties", "type": "boolean", "description": "false (default) = only priced hotels, so the dataset is a price list. true = also write a free row for every property Agoda lists but cannot price for the stay, with sold_out true and every price empty: an occupancy signal for a destination. Sold-out rows are never charged either way; a named hotel with no rate gets status sold_out.", "default": false }, "locale": { "title": "Locale", "type": "string", "description": "Agoda locale for hotel names, areas and city labels, e.g. \"en-us\" (default), \"ja-jp\", \"th-th\", \"ko-kr\", \"zh-cn\", \"de-de\". Prices and currency are not affected (set currency instead).", "default": "en-us" }, "sessions": { "title": "Parallel sessions", "minimum": 1, "maximum": 16, "type": "integer", "description": "Parallel proxy sessions (egress IPs), 1 to 16, e.g. 4 (default 4). More is faster; each session is paced separately by perIp. Leave the default unless Agoda throttles.", "default": 4 }, "perIp": { "title": "Requests per second per session", "minimum": 0.1, "maximum": 3, "type": "number", "description": "Requests per second per session, 0.1 to 3, e.g. 1 (default 1). Agoda tolerates about one request per second per IP; faster causes retries, not speed.", "default": 1 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify Proxy (default, datacenter group) is required: Agoda throttles a single busy IP within a few pages. Datacenter proxies are enough for this endpoint; residential is not needed.", "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 } } } } } } } } } }