# Tripadvisor API — hotel, restaurant & attraction reviews, ratings and place profiles from tripadvisor.com

> Reviews + the full place profile (rating histogram, subratings, amenities) for one or more Tripadvisor places, by page URL.
> ReefAPI engine `tripadvisor` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/tripadvisor/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /tripadvisor/v1/reviews — 1 credit
Reviews + the full place profile (rating histogram, subratings, amenities) for one or more Tripadvisor places, by page URL.

**Parameters:**
- `url` (string, optional) — Tripadvisor page URL of the hotel/restaurant/attraction (the reliable input — copy it from the browser). Provide this OR startUrls.
- `startUrls` (array, optional) — Several place URLs in one call (strings or {url:…} objects). One minted session is reused across them.
- `query` (string, optional) — UNRELIABLE: place-name lookup often fails to resolve ('Could not resolve a locationId'). Use `url` instead.
- `queries` (array, optional) — UNRELIABLE (same lookup as `query`): several place names in one call. Prefer `startUrls`.
- `maxReviews` (integer, optional, default 200) — How many of the newest reviews to fetch per place (1–10000). More reviews = longer runtime.
- `language` (string, optional, default "en") — Review language filter (ISO 639-1: en, es, de…). Use 'all' for every language (machine-translated).

**Returns:** results[]{place{location_id, name, entity_type, rating, review_count, ranking, price_range, rating_histogram, subratings, amenities, cuisines, hours}, reviews[]{id, rating, title, text, language, published_date, trip_type, stay_date, helpful_votes, photos, mgmt_response_text}}

**Example request body:**
```json
{
  "startUrls": [
    {
      "url": "https://www.tripadvisor.com/Hotel_Review-g45963-d91703-Reviews-Bellagio-Las_Vegas_Nevada.html"
    }
  ],
  "maxReviews": 45
}
```

### POST /tripadvisor/v1/places/list — 2 credits
Discover hotels, restaurants or attractions in a city/area (name, rating, review count) — the feeder for `reviews`.

**Parameters:**
- `location` (string, required) — City or area name. Resolved to a Tripadvisor geo automatically (or pin it exactly with geo_id).
- `category` (enum, optional, default "hotels") — What kind of places to list (singular forms also accepted). [one of: hotels, restaurants, attractions]
- `max_results` (integer, optional, default 30) — How many places to return (1–500). The engine pages the results internally.
- `geo_id` (string, optional) — Advanced: Tripadvisor geo ID (the g-number in URLs) — skips the location lookup.
- `location_slug` (string, optional) — Advanced: the URL slug that pairs with geo_id.

**Returns:** results[]{location_id, name, entity_type, rating, review_count, url, price_tier}

**Example request body:**
```json
{
  "location": "Las Vegas",
  "category": "hotels",
  "geo_id": "45963",
  "location_slug": "Las_Vegas_Nevada",
  "max_results": 30
}
```

### POST /tripadvisor/v1/detail — 2 credits
Full profile for one Tripadvisor hotel, restaurant or attraction by page URL: overall rating, total reviews, ranking, price level, the per-star rating breakdown, category subratings (cleanliness / service / value / location / food / atmosphere), amenities, cuisines, address, coordinates and phone.

**Parameters:**
- `url` (string, required) — Tripadvisor page URL of the hotel/restaurant/attraction (copy it from the browser, or get it from `search` / `places/list`).

**Returns:** place{location_id, name, entity_type, rating, review_count, ranking, price_range, rating_histogram, subratings, amenities, cuisines, address, latitude, longitude, phone, url}

**Example request body:**
```json
{
  "url": "https://www.tripadvisor.com/Hotel_Review-g45963-d91703-Reviews-Bellagio-Las_Vegas_Nevada.html"
}
```

### POST /tripadvisor/v1/search — 1 credit
Find Tripadvisor places (hotels, restaurants, attractions) and destinations by name — the typeahead the site's own search box uses. Returns the matching location IDs + page URLs to feed into `reviews` or `detail`.

**Parameters:**
- `query` (string, required) — Place or destination name to look up (e.g. 'Bellagio Las Vegas', 'Eiffel Tower', 'Rome').
- `type` (enum, optional) — Optional: keep only one kind of result. [one of: hotel, restaurant, attraction, geo]
- `limit` (integer, optional, default 10) — How many candidates to return (1–30).

**Returns:** results[]{location_id, name, entity_type, url}

**Example request body:**
```json
{
  "query": "Bellagio Las Vegas",
  "limit": 5
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=tripadvisor
- Human docs page: https://reefapi.com/docs/tripadvisor
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt