# TripAdvisor Reputation Event Monitor — Stateful Typed Events (`bovi/tripadvisor-reputation-monitor`) Actor

**Stateful TripAdvisor monitor that emits TYPED EVENTS** — `new_review`, `rating_crossed`, `rank_moved`, `review_velocity_spike`, `owner_response_gap`, `review_count_milestone`. NOT a review dump. Persists per-property state in Apify KV; re-polls and emits ONLY what changed.

- **URL**: https://apify.com/bovi/tripadvisor-reputation-monitor.md
- **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community)
- **Categories:** Marketing, Business, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 tripadvisor reputation event monitor — stateful typed events

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Reputation Event Monitor

**Monitors TripAdvisor hotels, restaurants, and attractions and emits TYPED EVENTS** — not review dumps. The actor re-polls your watchlist on each scheduled run, diffs against persisted state in Apify KV store, and pushes only what changed: new reviews, rating drops, rank shifts, unanswered complaints, and velocity spikes.

Built for hotel GMs, restaurant groups, and reputation-management SaaS platforms that need *actionable signals* routed to Slack, n8n, or their own webhook — not a spreadsheet to manually diff every morning.

### What Makes This Different from Review Scrapers

Most TripAdvisor actors on the Apify Store are **snapshot scrapers** — they dump all reviews on every run and leave the diffing to you. You pay for 5,000 reviews when you only wanted to know about the 3 new ones since yesterday, and you still have to wire your own logic to detect a rating drop or find unanswered complaints.

This actor does that diffing **for you**, inside the actor, using a stateful Apify KV store. You get a clean typed-event stream:

| Event | What it means |
|---|---|
| `new_review` | A review ID not seen on the previous run |
| `complaint` | New review with rating ≤ your threshold (default 2★) |
| `rating_crossed` | Overall property rating crossed a watched threshold (e.g. fell below 4.0) |
| `rank_moved` | Destination ranking shifted by ≥ N positions |
| `review_velocity_spike` | More than N new reviews in one run — possible viral moment or review-bomb |
| `owner_response_gap` | A negative review has had no management response for ≥ N days |
| `review_count_milestone` | Total review count hit a round number (100, 500, 1k, ...) |

Route each event type differently: send `complaint` and `owner_response_gap` to a GM's Slack, send `rating_crossed` to a PagerDuty alert, archive everything else to a spreadsheet.

### How It Works

1. **Warm-GET bootstrap** — for each property, fetches the TripAdvisor page to establish a session and extract rating, review count, and destination rank from the HTML.
2. **GraphQL poll** — fetches the 20 most recent reviews via TripAdvisor's internal `getReviewListPageForLocation` GraphQL endpoint.
3. **KV-state diff** — loads the previous run's state from a named Apify KV store and computes the delta.
4. **Event emission** — pushes only the typed events that passed your filters to the dataset, and charges one PPE event per emission.
5. **State update** — writes the updated state (seen review IDs, last rating, last rank, unanswered negatives) back to KV for the next run.

**First run:** bootstraps baseline only. No events emitted. This is by design — you need a "before" snapshot to produce a "what changed" diff.

### Input

```json
{
  "propertyUrls": [
    "https://www.tripadvisor.com/Hotel_Review-g60763-d93589-Reviews-The_Plaza-New_York_City_New_York.html",
    "https://www.tripadvisor.com/Restaurant_Review-g60763-d456789-Reviews-Le_Bernardin-New_York.html"
  ],
  "kvStoreName": "tripadvisor-reputation-state",
  "negativeThreshold": 2,
  "ratingCrossedThresholds": [4.0, 3.5],
  "rankMovedMinDelta": 3,
  "velocitySpikeMinDelta": 5,
  "ownerResponseGapDays": 3,
  "proxyConfiguration": { "useApifyProxy": true, "proxyGroups": ["RESIDENTIAL"] }
}
```

All thresholds are configurable. Use `eventTypes` to filter which event types reach the dataset (useful when chaining actors in a workflow — e.g. route only `complaint` to a notification actor).

### Output Schema

Every dataset record is a flat event dict:

| Field | Type | Description |
|---|---|---|
| `event_type` | string | One of the 7 typed events above |
| `severity` | string | `info` or `warning` |
| `property_id` | number | TripAdvisor location ID |
| `property_name` | string | Property display name |
| `property_url` | string | TripAdvisor URL |
| `property_rating` | number | Current overall rating |
| `property_review_count` | number | Current total reviews |
| `property_rank` | number | Current destination rank |
| `summary` | string | Human-readable one-line summary of the event |
| `current_value` | string | Current value (e.g. new rating, new rank) |
| `previous_value` | string | Previous value (e.g. old rating, old rank) |
| `review_id` | number | Review ID (for review events) |
| `review_rating` | number | Star rating 1-5 (for review events) |
| `review_title` | string | Review title (for review events) |
| `review_text` | string | Review text, truncated to 500 chars (for review events) |
| `review_date` | string | ISO-8601 review creation date |
| `review_username` | string | TripAdvisor username |
| `mgmt_responded` | boolean | Whether management has responded |
| `days_without_response` | number | Days since review posted without response (for gap events) |
| `emitted_at` | string | ISO-8601 timestamp of event detection |

### Proxy Requirement

**Residential proxies are required.** TripAdvisor blocks datacenter IP ranges. This actor is designed to run on the **Apify platform** where Apify residential proxies are available via `proxyConfiguration`. The buyer's Apify account pays for proxy compute — the actor author does not bear proxy costs.

Set `proxyConfiguration: { "useApifyProxy": true, "proxyGroups": ["RESIDENTIAL"] }` in your input. The actor defaults to RESIDENTIAL if no proxy configuration is provided but will log a warning.

### Scheduling

Run daily or every 12 hours via Apify Scheduler. The KV store persists between runs — as long as you use the same `kvStoreName`, the actor knows what it already saw.

Example: monitor 50 competitor hotels at 6am every morning, route `complaint` and `rating_crossed` events to your CRM via a webhook actor.

### Supported Property Types

- Hotels and accommodation (`Hotel_Review-*`)
- Restaurants (`Restaurant_Review-*`)
- Attractions and experiences (`Attraction_Review-*`)

Each property type uses the same underlying GraphQL endpoint. Airline reviews use a different endpoint structure and are not supported in this version.

### Integrations

Built for hotel GMs, restaurant groups, and reputation-SaaS platforms routing actionable review events into their alert pipelines — the JSON/dataset output drops into the tools you already run, no glue code:

- **n8n / Make / Zapier** — trigger a run or pipe every new dataset item into 500+ apps (Google Sheets, Airtable, Slack, HubSpot, your database) with no code: [n8n](https://docs.apify.com/platform/integrations/n8n), [Make](https://docs.apify.com/platform/integrations/make), [Zapier](https://docs.apify.com/platform/integrations/zapier).
- **Webhooks** — fire your own endpoint the moment a run finishes, to push results straight into your pipeline ([docs](https://docs.apify.com/platform/integrations/webhooks)).
- **MCP server** — expose this actor as a tool to Claude, Cursor, or any [MCP client](https://mcp.apify.com) so an AI agent can pull this data mid-conversation ([guide](https://blog.apify.com/how-to-use-mcp/)).
- **API & SDKs** — fetch the dataset as JSON, CSV, or Excel through the Apify REST API or the Python / JS SDKs.

See all [Apify integrations](https://apify.com/integrations).

### Legal Notes

This actor monitors only publicly visible TripAdvisor pages. No account login is used, no personal data beyond what TripAdvisor publicly displays is collected. Monitor your own properties and publicly visible competitor data. US-based buyers should be aware that public competitor monitoring is generally lawful under US law; EU buyers should consult local data regulations on public data collection.

### MCP Support

This actor is callable via the Apify MCP server for AI agent workflows:

```
Tool: apify/tripadvisor-reputation-monitor
Input: { "propertyUrls": [...], "eventTypes": ["complaint", "rating_crossed"] }
```

Use it in n8n, Make, or any MCP-compatible AI agent to receive structured reputation events without building your own scraper or diff logic.

### Pricing

Pay per event ($0.005/event). A property monitored daily that generates 3 new reviews and 1 rating tick costs roughly $0.02/day — orders of magnitude cheaper than a $300/month reputation SaaS seat.

The first run is a free baseline bootstrap that emits 0 events.

# Actor input Schema

## `propertyUrls` (type: `array`):

TripAdvisor property URLs to monitor. Each URL should point to a hotel, restaurant, or attraction page. Example: \['https://www.tripadvisor.com/Hotel\_Review-g60763-d93589-Reviews-The\_Plaza-New\_York\_City\_New\_York.html']. The actor extracts the location ID automatically — you can also mix hotel, restaurant, and attraction URLs in one run.

## `kvStoreName` (type: `string`):

Name of the Apify Key-Value store used to persist per-property state between runs. Defaults to 'tripadvisor-reputation-state'. Use the same name across scheduled runs to enable stateful diffing — if you change this, previous state is lost and the first run will emit no events (it bootstraps the baseline instead).

## `eventTypes` (type: `array`):

Filter which typed events to emit. Leave empty to emit ALL event types. Valid values: 'new\_review' (any new review since last run), 'complaint' (new review with rating <= negativeThreshold), 'rating\_crossed' (overall rating crossed a threshold), 'rank\_moved' (destination ranking changed by >= rankMovedMinDelta), 'review\_velocity\_spike' (review count jumped more than velocitySpikeMinDelta), 'owner\_response\_gap' (negative review unanswered for >= ownerResponseGapDays), 'review\_count\_milestone' (total review count hit a round number). Useful for routing: e.g. send only 'complaint' to Slack, send 'rating\_crossed' to a PagerDuty webhook. Allowed values: new\_review, complaint, rating\_crossed, rank\_moved, review\_velocity\_spike, owner\_response\_gap, review\_count\_milestone.

## `negativeThreshold` (type: `integer`):

Reviews with rating at or below this value are flagged as a 'complaint' event (in addition to the standard 'new\_review' event). Default: 2. Set to 3 to also flag 3-star reviews. Set to 0 to disable complaint detection.

## `ratingCrossedThresholds` (type: `array`):

Emit a 'rating\_crossed' event when the overall property rating crosses any of these values (in either direction — falling below or recovering above). Example: \[4.0, 3.5] emits an event when a 4.1-star property drops to 3.9, or when a 3.8 recovers to 4.1. Leave empty to disable rating-crossing detection.

## `rankMovedMinDelta` (type: `integer`):

Emit a 'rank\_moved' event when the property's destination ranking changes by at least this many positions. Default: 3 (so a shift from #10 to #12 triggers an event, but #10 to #11 does not). Set to 1 to catch every single-position move.

## `velocitySpikeMinDelta` (type: `integer`):

Emit a 'review\_velocity\_spike' event when more than this many NEW reviews appear in a single run. Default: 5 — useful for spotting viral moments, review-bombing attacks, or incentivized-review bursts. For properties that normally get 1-2 reviews/day, a value of 5 catches anomalies. For busy properties (100+ reviews/day), you may want 20-50.

## `ownerResponseGapDays` (type: `integer`):

Emit an 'owner\_response\_gap' event for each negative review (rating <= negativeThreshold) that has had NO management response for at least this many days. Default: 3. Helps hotel GMs hit their response-time KPI. Set to 0 to disable.

## `proxyConfiguration` (type: `object`):

Apify proxy configuration. The actor REQUIRES residential proxies for reliable access to TripAdvisor — datacenter IPs are not reliable. The recommended setting is useApifyProxy: true with proxyGroups: \['RESIDENTIAL']. If you leave this empty, the actor will attempt to use Apify's default residential proxy group automatically.

## `maxPropertiesPerRun` (type: `integer`):

Maximum number of properties to monitor in a single run. Default: 50. Useful if you have a large watchlist but want to split runs for speed or cost control. Properties are processed in the order they appear in propertyUrls.

## Actor input object example

```json
{
  "propertyUrls": [
    "https://www.tripadvisor.com/Hotel_Review-g60763-d93589-Reviews-The_Plaza-New_York_City_New_York.html"
  ],
  "kvStoreName": "tripadvisor-reputation-state",
  "negativeThreshold": 2,
  "ratingCrossedThresholds": [
    4,
    3.5
  ],
  "rankMovedMinDelta": 3,
  "velocitySpikeMinDelta": 5,
  "ownerResponseGapDays": 3,
  "maxPropertiesPerRun": 50
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset containing Tripadvisor Reputation Monitor records (property\_name, event\_type, severity, summary, current\_value, previous\_value, review\_rating, mgmt\_responded, days\_without\_response, property\_url, review\_date, emitted\_at).

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "propertyUrls": [
        "https://www.tripadvisor.com/Hotel_Review-g60763-d93589-Reviews-The_Plaza-New_York_City_New_York.html"
    ],
    "kvStoreName": "tripadvisor-reputation-state",
    "negativeThreshold": 2,
    "ratingCrossedThresholds": [
        4,
        3.5
    ],
    "rankMovedMinDelta": 3,
    "velocitySpikeMinDelta": 5,
    "ownerResponseGapDays": 3,
    "maxPropertiesPerRun": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("bovi/tripadvisor-reputation-monitor").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "propertyUrls": ["https://www.tripadvisor.com/Hotel_Review-g60763-d93589-Reviews-The_Plaza-New_York_City_New_York.html"],
    "kvStoreName": "tripadvisor-reputation-state",
    "negativeThreshold": 2,
    "ratingCrossedThresholds": [
        4,
        3.5,
    ],
    "rankMovedMinDelta": 3,
    "velocitySpikeMinDelta": 5,
    "ownerResponseGapDays": 3,
    "maxPropertiesPerRun": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("bovi/tripadvisor-reputation-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "propertyUrls": [
    "https://www.tripadvisor.com/Hotel_Review-g60763-d93589-Reviews-The_Plaza-New_York_City_New_York.html"
  ],
  "kvStoreName": "tripadvisor-reputation-state",
  "negativeThreshold": 2,
  "ratingCrossedThresholds": [
    4,
    3.5
  ],
  "rankMovedMinDelta": 3,
  "velocitySpikeMinDelta": 5,
  "ownerResponseGapDays": 3,
  "maxPropertiesPerRun": 50
}' |
apify call bovi/tripadvisor-reputation-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bovi/tripadvisor-reputation-monitor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/75gyr5hSfvMFuA91R/builds/sXREY5D3j17QXfSVh/openapi.json