# Tripadvisor Hotel Scraper — Hotels, Reviews · Travel Data API (`sian.agency/tripadvisor-hotel-scraper`) Actor Scrape Tripadvisor hotel listings with price, rating, ranking and optional reviews. Five search modes (geoId, location text, lat/lng, bounding box, URL/ID). Hospitality KPIs (avg rating, price/rank distribution) + HTML report. - **URL**: https://apify.com/sian.agency/tripadvisor-hotel-scraper.md - **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community) - **Categories:** Travel, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 hotel extracteds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Tripadvisor Hotel Scraper — Hotels, Reviews & Travel Data API 🏨 [![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![SIÁN-StreetEasy](https://img.shields.io/badge/SI%C3%81N-StreetEasy-FF4747)](https://apify.com/sian.agency/streeteasy-property-scraper?fpr=sian) [![SIÁN-Airbnb](https://img.shields.io/badge/SI%C3%81N-Airbnb-FF5A5F)](https://apify.com/sian.agency/airbnb-property-scraper?fpr=sian) [![SIÁN-Zillow](https://img.shields.io/badge/SI%C3%81N-Zillow-1F4E79)](https://apify.com/sian.agency/zillow-property-scraper?fpr=sian) #### 🎉 NEW: Bundle hotels + up to 20 reviews per hotel in a single run — no two-actor pipeline ##### Built for hospitality analysts, travel researchers, OTA teams, and reputation managers who need clean Tripadvisor data fast. --- ### 📋 Overview **Tripadvisor data without the two-actor dance.** Pull hotels, reviews, ratings, ranking, price, and accommodation type from anywhere on Tripadvisor — by city, coordinates, bounding box, hotel ID, or URL — in one structured run. **Why hospitality teams choose us:** - ✅ **5 search modes** — geoId, free-text location, lat/lng radius, bounding box, single hotel by ID, single hotel by URL - ⚡ **Direct-API wrapper** — sub-2-second/hotel, no Cloudflare/captcha brittleness like browser-scrapers - 🎯 **Bundled reviews enrichment** — opt-in `fetchReviews` pulls up to 20 reviews per hotel in the same run, no manual locationId hand-off - 💰 **Mid-market tiered pricing** — $0.008 FREE → $0.00125 DIAMOND per hotel, matching the proven voyager/booking-scraper curve - 💎 **Hospitality KPIs out of the box** — avg rating, price distribution, rank distribution, accommodation-type and style-tag tallies in a default HTML report - ✨ **NEW**: Stay-spec parameters (checkIn / checkOut / adults / rooms / currency) for live price quotes in any currency --- ### ✨ Features - 🧭 **5 Search Modes** — by Tripadvisor geo ID, free-text location, lat/lng + radius, bounding box, single hotel ID, or hotel URL - ⭐ **Rating + Ranking Capture** — Tripadvisor rating, review count, and exact rank position ("#1 of 1,881 hotels in Paris") - 💰 **Live Price Quotes** — minimum nightly price in any ISO currency for given checkIn/checkOut dates - 📝 **Reviews Enrichment** — up to 20 reviews per hotel with rating, trip type, visit date, and reviewer attribution - 🏨 **Accommodation Typing** — hotel category + style tags (Modern, Mid-range, Business, Boutique, Luxury, etc.) - 📍 **Full Address & Coordinates** — street, city, country, postal code, lat/lng - 📊 **HTML Hospitality Report** — auto-generated per run with median price, rating distribution, rank distribution, top cities, top accommodation types - 🔁 **Built-in Deduplication** — hotels deduped across overlapping queries - 📦 **Bulk Mode** (PAID) — multiple hotel IDs or URLs in a single run --- ### 🎬 Quick Start Run via Apify Console, the Apify API, or any HTTP client. Provide a `searchMode` plus the matching field (geoId, location, lat/lng, boundingBox, locationId, or url) and get clean structured rows in your dataset. ```bash curl -X POST 'https://api.apify.com/v2/acts/sian.agency~tripadvisor-hotel-scraper/runs?token=YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"searchMode": "bylocation", "location": "Paris", "maxResults": 30}' ```` *** ### 🚀 Getting Started (3 Simple Steps) #### Step 1: Pick your search mode Choose how you want to find hotels — by city name (`bylocation`), Tripadvisor numeric geo (`bygeoid`), coordinates + radius (`bycoordinates`), bounding box (`byboundingbox`), or a single hotel ID/URL (`byid` / `byurl`). #### Step 2: (Optional) Specify your stay Add `checkIn`, `checkOut`, `adults`, `rooms`, and `currency` to pull live nightly price quotes. Skip these to get the default Tripadvisor price snapshot. #### Step 3: (Optional) Enable reviews enrichment (PAID) Set `fetchReviews: true` to pull up to 20 reviews per hotel in the same run — no manual locationId pipeline needed. **That's it! In under a minute, you'll have:** - Clean structured hotel rows in JSON / CSV / Excel - An HTML hospitality report saved to the key-value store - (Optional) per-hotel review rows ready for sentiment analysis *** ### 📥 Input Configuration | Field | Type | Required | Description | |-------|------|----------|-------------| | `searchMode` | string | Yes | `bygeoid` · `bylocation` · `bycoordinates` · `byboundingbox` · `byid` · `byurl` | | `location` | string | conditional | Free-text city/region for `bylocation` mode | | `geoId` | integer | conditional | Tripadvisor numeric geo ID (e.g. 187147 = Paris) | | `latitude` / `longitude` | number | conditional | Center coordinates for radial search | | `radius` | number | No | Search radius in km (0.1–50, default 5) | | `boundingBox` | string | conditional | `north,east,south,west` decimal degrees | | `locationId` | integer | conditional | Single hotel ID for `byid` mode | | `locationIds` | array | No (PAID) | Bulk hotel IDs | | `url` | string | conditional | Single Tripadvisor hotel URL for `byurl` mode | | `urls` | array | No (PAID) | Bulk hotel URLs | | `checkIn` / `checkOut` | string | No | Stay dates (YYYY-MM-DD) for live price quotes | | `adults` | integer | No | Adult guest count (1–16, default 2) | | `rooms` | integer | No | Room count (1–8, default 1) | | `currency` | string | No | ISO currency code (default USD) | | `maxResults` | integer | No | Hotels per query (1–300, default 30) | | `fetchReviews` | boolean | No (PAID) | Pull up to 20 reviews per hotel | **Example — search by city:** ```json { "searchMode": "bylocation", "location": "Paris", "checkIn": "2026-06-15", "checkOut": "2026-06-17", "adults": 2, "currency": "USD", "maxResults": 30 } ``` **Example — by coordinates with reviews enrichment (PAID):** ```json { "searchMode": "bycoordinates", "latitude": 48.8566, "longitude": 2.3522, "radius": 5, "fetchReviews": true, "maxResults": 50 } ``` **Example — single hotel by ID:** ```json { "searchMode": "byid", "locationId": 229968 } ``` *** ### 📤 Output Results are saved to the Apify dataset with **20+ fields** per hotel, plus a separate row per review when enrichment is on. | Field | Type | Description | |-------|------|-------------| | `hotelId` | integer | Tripadvisor numeric hotel ID | | `name` | string | Hotel display name | | `rating` | number | 0–5 Tripadvisor rating | | `reviewCount` | integer | Total reviews on Tripadvisor | | `accommodationType` | string | Hotel · B\&B · Specialty Lodging · Inn | | `styleTags` | array | Modern · Mid-range · Business · Boutique · Luxury | | `pricing` | object | `priceMin`, `currency` | | `ranking` | object | `label`, `position`, `total` | | `address` | object | `street`, `city`, `country`, `postalCode`, `full` | | `location` | object | `latitude`, `longitude` | | `contact` | object | `phone` (search) · `email`, `officialUrl` (detail) | | `media` | object | `thumbnailUrl`, `photos` | | `url` | string | Full Tripadvisor URL | | `parentGeo` | string | Parent city name | **Example hotel row:** ```json { "hotelId": 229968, "name": "Hôtel Astra Opéra - Astotel", "rating": 5, "reviewCount": 882, "accommodationType": "Hotel", "styleTags": ["Modern", "Mid-range", "Business"], "pricing": { "priceMin": 268, "currency": "USD" }, "ranking": { "label": "#1 of 1,881 hotels in Paris", "position": 1, "total": 2422 }, "address": { "city": "Paris", "country": "France", "full": "29 Rue Caumartin, 75009 Paris" }, "location": { "latitude": 48.87178, "longitude": 2.328087 }, "contact": { "phone": "+33 1 42 65 15 15" }, "url": "https://www.tripadvisor.com/Hotel_Review-g187147-d229968-Reviews-Hotel_Astra_Opera_Astotel-Paris.html", "scrapedAt": "2026-05-19T22:40:00.000Z" } ``` **Example review row (with `fetchReviews: true`):** ```json { "reviewId": 1060326551, "hotelId": 229968, "reviewTitle": "A real find!", "text": "A small hotel in central Paris, the staff were exceptional…", "rating": 5.0, "publishedDate": "3 days ago", "dateVisited": "May 2026", "tripType": "Family", "author": "Ann H", "authorContributions": "44 contributions" } ``` *** ### 💼 Use Cases & Examples #### 1. Hospitality intelligence **Hospitality analysts tracking competitor inventory across cities.** **Input:** `searchMode: "bylocation"`, `location: "Paris"`, `maxResults: 100` **Output:** 100 hotels with rating, rank position, price, style tags, accommodation type. **Use:** Build a daily competitor dashboard. Track how a competitor's ranking moves over time. #### 2. Reputation analysis **Reputation managers monitoring guest sentiment.** **Input:** `searchMode: "byid"`, `locationId: 229968`, `fetchReviews: true` **Output:** Hotel detail + 20 latest reviews with rating, trip type, visit month, reviewer. **Use:** Pipe review text into your sentiment-analysis stack. Track rating drift week-over-week. #### 3. OTA market benchmarking **OTA pricing teams comparing inventory across destinations.** **Input:** `searchMode: "bygeoid"`, multiple runs across top-50 city geoIds with same checkIn/checkOut. **Output:** Per-city hotel inventory with live price quotes in your currency. **Use:** Find under-priced hotels by city. Set automated alerts on rank-position changes. #### 4. Travel research **Academic and consulting teams building hotel comparables.** **Input:** `searchMode: "bycoordinates"`, `latitude/longitude/radius`. **Output:** All hotels within X km of a point, with rating, price, rank. **Use:** Build geographic comparables for hotel-market academic studies or M\&A advisory work. #### 5. Acquisition due diligence **Hospitality M\&A teams snapshotting acquisition targets.** **Input:** `searchMode: "byurl"`, full Tripadvisor URL of the target hotel + `fetchReviews: true`. **Output:** Hotel detail (locationId, address, photos, official URL, ranking) + 20 latest reviews. **Use:** Generate a one-page Tripadvisor footprint per target during diligence calls. #### 6. Vacation rental research **Vacation-rental platforms benchmarking adjacent supply.** **Input:** `searchMode: "byboundingbox"`, bounding box around a target neighborhood. **Output:** All Tripadvisor-listed accommodations in the bbox with style tags + price. **Use:** Quantify hotel competition for short-term rentals in a specific catchment. #### 7. Hospitality benchmarking dashboards **BI/analytics teams building hospitality dashboards.** **Input:** Scheduled run per city with `maxResults: 200`. **Output:** Time-series hotel inventory with price, rating, rank position. **Use:** Power a Looker / Power BI / Metabase board with daily Tripadvisor snapshots. *** ### 🔗 Integration Examples #### JavaScript/Node.js ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_TOKEN' }); const run = await client.actor('sian.agency/tripadvisor-hotel-scraper').call({ searchMode: 'bylocation', location: 'Paris', maxResults: 30 }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items[0]); ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_TOKEN') run = client.actor('sian.agency/tripadvisor-hotel-scraper').call( run_input={'searchMode': 'bylocation', 'location': 'Paris', 'maxResults': 30} ) for item in client.dataset(run['defaultDatasetId']).iterate_items(): print(item) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/sian.agency~tripadvisor-hotel-scraper/runs?token=YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"searchMode": "bylocation", "location": "Paris", "maxResults": 30}' ``` #### Automation Workflows (N8N / Zapier / Make) 1. **Trigger**: Schedule (e.g. daily 9 AM) 2. **HTTP Request**: Call the actor API per city 3. **Process**: Aggregate hotel rows, diff against prior run for rank-position changes 4. **Action**: Slack alert when a hotel rank moves > 5 positions, or push to BI warehouse *** ### 📊 Performance & Pricing #### FREE Tier (Try It Now) - **25 hotels** per run — full feature access, same quality - All 5 search modes available - No credit card required - Perfect for evaluation and small projects #### PAID Tier (Production Ready) - **Unlimited** hotels per run - Bulk locationIds / URLs supported - Reviews enrichment available (up to 20 reviews per hotel) - Pay-per-result tiered pricing: only charged for successful rows 💰 **Mid-market tiered curve** — $0.008 FREE → $0.0029 BRONZE → $0.0025 SILVER → $0.002 GOLD → $0.0015 PLATINUM → $0.00125 DIAMOND per hotel. Reviews charged separately, capped at 20 per hotel by upstream. 🔗 [View current pricing](https://apify.com/sian.agency/tripadvisor-hotel-scraper?fpr=sian) *** ### ❓ Frequently Asked Questions **Q: How many hotels can I process in one run?** A: FREE tier: 25 hotels per run. PAID tier: unlimited, with bulk input arrays. **Q: How many reviews per hotel can I get?** A: Tripadvisor's upstream caps at 20 reviews per hotel — there is no pagination available, so the maximum is a hard 20 regardless of how many reviews the hotel actually has. **Q: What output formats are available?** A: JSON, CSV, Excel, XML, and HTML — export directly from the Apify dataset. **Q: Can I get hotels for a specific check-in/check-out date?** A: Yes — pass `checkIn`, `checkOut`, `adults`, `rooms`, and `currency` and the `priceMin` field reflects the live nightly quote for those dates in that currency. **Q: What's the difference between "search" modes and "detail" modes?** A: Search modes (`bygeoid`, `bylocation`, `bycoordinates`, `byboundingbox`) return many hotels with price/rating/ranking. Detail modes (`byid`, `byurl`) return a single hotel with email, photos, and parent geo — no live pricing or ranking (those only exist in search results). **Q: Does it work for hotels outside the US/Europe?** A: Yes — Tripadvisor's global coverage is supported. Use `bylocation` with any city name worldwide, or pass any country's lat/lng. **Q: How accurate is the data?** A: Data is pulled from Tripadvisor's structured backend — same source as the public site. Rating, review count, ranking, and address are exact mirrors. **Q: Is this legal?** A: Yes — we only extract publicly available data shown on Tripadvisor's website. See the legal section below. *** ### 🐛 Troubleshooting **"Could not resolve {location} to a Tripadvisor geo"** - The free-text `location` was too vague or misspelled. Try a more specific term (e.g. "Paris, France" instead of "Paris"). - Alternatively use `searchMode: "bygeoid"` with a numeric geoId from a known Tripadvisor URL (the value after `-g` in the URL). **"Invalid Tripadvisor URL"** - The URL must start with `https://www.tripadvisor.com/Hotel_Review-g…-d…` (or a regional Tripadvisor domain like `.co.uk`, `.fr`). **Empty results from search** - Verify the geoId / coordinates / bounding box are valid. Some very remote areas have no hotel inventory on Tripadvisor. - Check `checkIn`/`checkOut` if provided — invalid date ranges return empty results. **Reviews enrichment returns fewer than 20 reviews** - Some hotels have fewer than 20 reviews total. That's expected — you get all available reviews, capped at 20. *** ### ⚖️ Is it legal to scrape data? Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers. You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/). *** ### ⚠️ Trademark Disclaimer This actor is an **independent third-party tool** developed by SIÁN Agency. It is **not affiliated with, endorsed by, or sponsored by Tripadvisor, LLC**. "Tripadvisor" is a registered trademark of Tripadvisor, LLC, used here for descriptive purposes only (nominative fair use) to identify the public data source this tool operates on. All trademarks remain the property of their respective owners. This tool extracts only publicly accessible information from Tripadvisor and is intended for lawful research, analytics, and business-intelligence purposes by Apify users. *** ### 🤝 Support [![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi) **Join our active support community** - For issues or questions, open an issue in the actor's repository - Check [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools - 📧 *** **Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)** # Actor input Schema ## `searchMode` (type: `string`): How to specify the hotels you want. • **bygeoid** — by Tripadvisor numeric geo ID (e.g. 187147 for Paris) • **bylocation** — by free-text location (e.g. "Paris", "Tokyo") • **bycoordinates** — by lat/lng + radius (km) • **byboundingbox** — by north,east,south,west bbox • **byid** — fetch one hotel by locationId • **byurl** — fetch one hotel by Tripadvisor URL ## `location` (type: `string`): City, region, or country name. Used when Search Mode = bylocation. Example: "Paris", "New York", "Bali". ## `geoId` (type: `integer`): Numeric Tripadvisor geo ID. Example: 187147 = Paris, 60763 = New York City, 294229 = Bali. ## `latitude` (type: `number`): Center latitude for radial search. ## `longitude` (type: `number`): Center longitude for radial search. ## `radius` (type: `number`): Search radius in kilometers. Default 5 km. Range 0.1–50. ## `boundingBox` (type: `string`): Geographic bounding box as four comma-separated decimal degrees: north,east,south,west. Example: "48.90,2.42,48.81,2.22". ## `locationId` (type: `integer`): Tripadvisor numeric hotel ID (the value after "-d" in any hotel review URL). ## `locationIds` (type: `array`): Array of numeric hotel IDs for bulk detail extraction. PAID tier only. ## `url` (type: `string`): Full Tripadvisor hotel URL (https://www.tripadvisor.com/Hotel\_Review-g…-d…). ## `urls` (type: `array`): Array of Tripadvisor hotel URLs for bulk detail extraction. PAID tier only. ## `checkIn` (type: `string`): Optional check-in date (YYYY-MM-DD). When provided with checkOut, price quotes reflect those dates. ## `checkOut` (type: `string`): Optional check-out date (YYYY-MM-DD). ## `adults` (type: `integer`): Number of adult guests (1–16). Default 2. ## `rooms` (type: `integer`): Number of rooms (1–8). Default 1. ## `currency` (type: `string`): ISO currency code for price quotes (e.g. USD, EUR, GBP). Default USD. ## `maxResults` (type: `integer`): Hard cap on hotels returned per query. Auto-paginates until the cap is reached or the search is fully drained. Default 30 = one API page. FREE tier is always capped at 25 hotels per run. ## `fetchReviews` (type: `boolean`): When ON, fetches up to 20 reviews per hotel (1 extra API call per hotel). Adds a ReviewExtracted charge per review pushed. Disabled on FREE tier. Hard upstream cap: 20 reviews per hotel. ## Actor input object example ```json { "searchMode": "bylocation", "location": "Paris", "geoId": 187147, "latitude": 48.8566, "longitude": 2.3522, "radius": 5, "boundingBox": "48.90,2.42,48.81,2.22", "locationId": 229968, "url": "https://www.tripadvisor.com/Hotel_Review-g187147-d229968-Reviews-Hotel_Astra_Opera_Astotel-Paris_Ile_de_France.html", "checkIn": "2026-06-15", "checkOut": "2026-06-17", "adults": 2, "rooms": 1, "currency": "USD", "maxResults": 30, "fetchReviews": false } ``` # Actor output Schema ## `results` (type: `string`): Structured Tripadvisor hotel rows with price, rating, ranking, accommodation type, plus (when enabled) review rows. ## `htmlReport` (type: `string`): HTML summary with run stats, hospitality KPIs (avg rating, price/rank distribution), per-city + per-type breakdowns, and per-query totals. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("sian.agency/tripadvisor-hotel-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("sian.agency/tripadvisor-hotel-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call sian.agency/tripadvisor-hotel-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sian.agency/tripadvisor-hotel-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Tripadvisor Hotel Scraper — Hotels, Reviews · Travel Data API", "description": "Scrape Tripadvisor hotel listings with price, rating, ranking and optional reviews. Five search modes (geoId, location text, lat/lng, bounding box, URL/ID). Hospitality KPIs (avg rating, price/rank distribution) + HTML report.", "version": "1.0", "x-build-id": "cODNo7rehP3XA2UNG" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~tripadvisor-hotel-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-tripadvisor-hotel-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/sian.agency~tripadvisor-hotel-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-tripadvisor-hotel-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/sian.agency~tripadvisor-hotel-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-tripadvisor-hotel-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": { "searchMode": { "title": "🧭 Search Mode", "enum": [ "bygeoid", "bylocation", "bycoordinates", "byboundingbox", "byid", "byurl" ], "type": "string", "description": "How to specify the hotels you want.\n\n• **bygeoid** — by Tripadvisor numeric geo ID (e.g. 187147 for Paris)\n• **bylocation** — by free-text location (e.g. \"Paris\", \"Tokyo\")\n• **bycoordinates** — by lat/lng + radius (km)\n• **byboundingbox** — by north,east,south,west bbox\n• **byid** — fetch one hotel by locationId\n• **byurl** — fetch one hotel by Tripadvisor URL", "default": "bylocation" }, "location": { "title": "🌍 Location (free text)", "type": "string", "description": "City, region, or country name. Used when Search Mode = bylocation. Example: \"Paris\", \"New York\", \"Bali\"." }, "geoId": { "title": "📍 Geo ID", "minimum": 1, "type": "integer", "description": "Numeric Tripadvisor geo ID. Example: 187147 = Paris, 60763 = New York City, 294229 = Bali." }, "latitude": { "title": "🌐 Latitude", "minimum": -90, "maximum": 90, "type": "number", "description": "Center latitude for radial search." }, "longitude": { "title": "🌐 Longitude", "minimum": -180, "maximum": 180, "type": "number", "description": "Center longitude for radial search." }, "radius": { "title": "📏 Radius (km)", "minimum": 0.1, "maximum": 50, "type": "number", "description": "Search radius in kilometers. Default 5 km. Range 0.1–50.", "default": 5 }, "boundingBox": { "title": "🗺 Bounding Box (n,e,s,w)", "type": "string", "description": "Geographic bounding box as four comma-separated decimal degrees: north,east,south,west. Example: \"48.90,2.42,48.81,2.22\"." }, "locationId": { "title": "🆔 Hotel ID", "minimum": 1, "type": "integer", "description": "Tripadvisor numeric hotel ID (the value after \"-d\" in any hotel review URL)." }, "locationIds": { "title": "📋 Bulk Hotel IDs (PAID)", "uniqueItems": true, "type": "array", "description": "Array of numeric hotel IDs for bulk detail extraction. PAID tier only.", "items": { "type": "string" } }, "url": { "title": "🔗 Hotel URL", "type": "string", "description": "Full Tripadvisor hotel URL (https://www.tripadvisor.com/Hotel_Review-g…-d…)." }, "urls": { "title": "📋 Bulk Hotel URLs (PAID)", "uniqueItems": true, "type": "array", "description": "Array of Tripadvisor hotel URLs for bulk detail extraction. PAID tier only.", "items": { "type": "string" } }, "checkIn": { "title": "📅 Check-in date", "type": "string", "description": "Optional check-in date (YYYY-MM-DD). When provided with checkOut, price quotes reflect those dates." }, "checkOut": { "title": "📅 Check-out date", "type": "string", "description": "Optional check-out date (YYYY-MM-DD)." }, "adults": { "title": "👥 Adults", "minimum": 1, "maximum": 16, "type": "integer", "description": "Number of adult guests (1–16). Default 2.", "default": 2 }, "rooms": { "title": "🛏 Rooms", "minimum": 1, "maximum": 8, "type": "integer", "description": "Number of rooms (1–8). Default 1.", "default": 1 }, "currency": { "title": "💱 Currency", "type": "string", "description": "ISO currency code for price quotes (e.g. USD, EUR, GBP). Default USD.", "default": "USD" }, "maxResults": { "title": "📊 Max results per query", "minimum": 1, "maximum": 300, "type": "integer", "description": "Hard cap on hotels returned per query. Auto-paginates until the cap is reached or the search is fully drained. Default 30 = one API page. FREE tier is always capped at 25 hotels per run.", "default": 30 }, "fetchReviews": { "title": "📝 Include reviews (PAID)", "type": "boolean", "description": "When ON, fetches up to 20 reviews per hotel (1 extra API call per hotel). Adds a ReviewExtracted charge per review pushed. Disabled on FREE tier. Hard upstream cap: 20 reviews per hotel.", "default": false } } }, "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 } } } } } } } } } } ```