{ "openapi": "3.0.1", "info": { "title": "TripAdvisor Reviews Scraper — Hotel Guest Reviews & Ratings", "description": "Every TripAdvisor review of any hotel: 1-5 bubbles, title, full text, six sub-ratings, stay date, trip type, reviewer, photos and the management response, in up to 30 site languages. Give TripAdvisor URLs, location ids or hotel names. No browser, no login. Pay per review.", "version": "1.0", "x-build-id": "nMFIQfdOh5McVszhl" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/kestrel~tripadvisor-reviews-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-kestrel-tripadvisor-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/kestrel~tripadvisor-reviews-scraper/runs": { "post": { "operationId": "runs-sync-kestrel-tripadvisor-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/kestrel~tripadvisor-reviews-scraper/run-sync": { "post": { "operationId": "run-sync-kestrel-tripadvisor-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": "TripAdvisor hotel URLs", "uniqueItems": true, "type": "array", "description": "Hotel pages on any TripAdvisor domain, e.g. https://www.tripadvisor.com/Hotel_Review-g189158-d4509998-Reviews-Memmo_Alfama_Hotel-Lisbon.html — the geo id and slug do not have to be right, the numeric d is what counts. Any query string is fine.", "default": [], "items": { "type": "string" } }, "locationIds": { "title": "TripAdvisor location ids", "uniqueItems": true, "type": "array", "description": "The numeric ids after d in TripAdvisor URLs, e.g. 4509998 or d4509998 — what an earlier run's location_id gives you. The fastest path: no lookup at all.", "default": [], "items": { "type": "string" } }, "hotelNames": { "title": "Hotel names", "uniqueItems": true, "type": "array", "description": "Hotel names, ideally with the city (\"Memmo Alfama Lisbon\"). Resolved through TripAdvisor's own typeahead; a hit must share at least half of the words you typed, so a nonsense name comes back as an error row instead of a random hotel. The resolved name is in the hotel and status rows so you can check the match.", "default": [], "items": { "type": "string" } }, "languages": { "title": "Review languages", "uniqueItems": true, "type": "array", "description": "Which TripAdvisor sites to read — each site serves the reviews in its own language, machine-translated ones included: en (tripadvisor.com), en-gb, de, fr, es, it, pt (tripadvisor.com.br), nl, ja, zh, ru, sv, da, no, fi, pl, tr, el, ko, th, vi, id, cs, hu, he, en-au, en-ca, en-in, en-ie, en-sg. One hotel × one language = one job; the same review can appear once per language (as a translation), so pick the languages you need.", "default": [ "en" ], "items": { "type": "string" } }, "maxReviewsPerHotel": { "title": "Max reviews per hotel and language", "minimum": 0, "maximum": 20000, "type": "integer", "description": "0 = every review the site lists for the hotel in that language (10 per page; popular hotels run into the thousands, and each page is about a megabyte of residential proxy traffic). N = the newest N. The main cost control.", "default": 100 }, "maxRating": { "title": "Only reviews at or below this rating", "minimum": 0, "maximum": 5, "type": "number", "description": "0 = keep every review. 1-5 = keep only reviews with that many bubbles or fewer — 2 gives a complaints feed. Filtered reviews are never charged (the pages are still read, so combine with a sensible max).", "default": 0 }, "tripTypes": { "title": "Trip types", "uniqueItems": true, "type": "array", "description": "Keep only reviews from these trip types: family, couples, solo, business, friends. Empty = all. Filtered reviews are never charged.", "default": [], "items": { "type": "string" } }, "sinceDate": { "title": "Only reviews published on or after", "type": "string", "description": "YYYY-MM-DD, or relative so schedules never go stale: \"30 days\", \"2 weeks\", \"6 months\". Pages come newest first, so the run stops reading once a whole page predates the date — a daily schedule reads one or two pages per hotel. Empty = no date limit.", "default": "" }, "requireText": { "title": "Only reviews with a written text", "type": "boolean", "description": "Drop rating-only reviews before billing. TripAdvisor reviews almost always carry text, so this rarely removes much.", "default": false }, "includeTranslated": { "title": "Include machine-translated reviews", "type": "boolean", "description": "Each site shows reviews written in other languages as machine translations (rows carry translated = true and the original_language). Untick to keep only reviews written in the site's language — with several languages selected that also stops the same review arriving once per language.", "default": true }, "includeHotelRow": { "title": "Include a hotel row", "type": "boolean", "description": "Also emit one row per hotel and language with its ids, name, bubble rating and review count, the count of reviews per rating and per language, six sub-ratings, its ranking in the city, address, coordinates, phone, website and amenities. Never charged.", "default": true }, "sessions": { "title": "Parallel sessions", "minimum": 1, "maximum": 16, "type": "integer", "description": "How many residential proxy sessions (egress IPs) run in parallel. More is faster; each is paced separately.", "default": 2 }, "perIp": { "title": "Requests per second per session", "minimum": 0.1, "maximum": 3, "type": "number", "description": "Pace for each session. TripAdvisor serves 1 page/s per IP steadily; raising it causes rotations, not speed.", "default": 1 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify Proxy with the RESIDENTIAL group is required: TripAdvisor's bot gate refuses every datacenter range outright, and only residential IPs are served. Keep the default.", "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 } } } } } } } } } }