# Tripadvisor (/docs/tripadvisor)

Search Tripadvisor places and pull traveler reviews behind the unified schema

Search Tripadvisor for businesses and places (restaurants, hotels, attractions) and pull their traveler reviews. Search returns the canonical `Place` object and reviews the shared `Review` object, so your code reads Tripadvisor exactly like it reads Amazon, Google Shopping or Trustpilot.

Base URL: `/v1/tripadvisor/...`

It is a two-step flow, and the joining key is `url_path`. Call `search` to find a place, read `url_path` off the result, then pass it to `reviews` verbatim, without a leading slash.

  `search` defaults to the **United States** when you omit `location`, so a
  query for a place in Tokyo without `location=Tokyo,Japan` quietly returns
  American results. Always pass `location` unless you mean the US.

## Quickstart

### Find the place

Note that the query parameter is `q`, not `query`.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/tripadvisor/search?q=pizza%20restaurant&location=New%20York,New%20York,United%20States&depth=30" \
  -H "x-api-key: YOUR_API_KEY"
```

### Pull its traveler reviews

Pass the `url_path` from step 1 exactly as returned.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/tripadvisor/reviews?url_path=Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html&depth=30&sort_by=most_recent" \
  -H "x-api-key: YOUR_API_KEY"
```

## Places

| Endpoint                     | Credits | What it returns                                                                                      | Key parameters                                  |
| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `GET /v1/tripadvisor/search` | 1       | Places with name, category, star rating, total review count, and the `url_path` that identifies them | `q` (required), `location`, `language`, `depth` |

`depth` is the result count in multiples of 30: default 30, max 60 on this synchronous endpoint. The place `id` and absolute `url` are both derived from `url_path`.

## Reviews

| Endpoint                      | Credits | What it returns                                                                                      | Key parameters                                                                                           |
| ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `GET /v1/tripadvisor/reviews` | 1       | Star rating, title, full text, reviewer, attached photos, management replies, language, publish date | `url_path` (required), `depth`, `sort_by`, `rating`, `visit_type`, `search_reviews_keyword`, `translate`, `label`, `judgments` |

`depth` is in multiples of 10: default 10, max 30. `sort_by` takes `most_recent` or `detailed_reviews`. `rating` filters by traveler bucket (`excellent`, `very_good`, `average`, `poor`, `terrible`) rather than a star number, and `visit_type` by traveler type (`families`, `couples`, `solo`, `business`, `friends`).

## All endpoints

## Platform notes

**Neither endpoint paginates.** `depth` is the only size control on both, and the synchronous endpoints cap it at 60 results on search and 30 reviews on reviews. Deeper review history is a future async surface.

**Reviews are auto-translated by Tripadvisor.** `translate` defaults to true, and every review carries a `translated` flag plus its `original_language` so you can tell what was rewritten. Set `translate=false` if you want the text as written.

**First calls are slow, then cached.** A cold call takes roughly 15 to 45 seconds because the upstream settles a task before answering; repeats serve from cache. Set client timeouts accordingly. Search caches for 2 minutes and reviews for 5, a cache hit costs 0 credits, and `Cache-Control: no-cache` requests a billed refresh.

**A place with no matching reviews returns `404`.** It is refunded automatically and never billed. Note that filters narrow the match, so a tight `rating` plus `search_reviews_keyword` combination can produce a not-found on a place that does have reviews.

## Labels

`/v1/tripadvisor/reviews`, `/v1/tripadvisor/restaurant/reviews`, `/v1/tripadvisor/attraction/reviews` and `/v1/tripadvisor/cruise/reviews` label each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`.

## Next steps

- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [Caching](/docs/caching.md): Freshness windows, and how cache hits keep your bill down.
- [API reference](/docs/api-reference.md): Every Tripadvisor parameter and response field.
- [Trustpilot](/docs/trustpilot.md): Company reviews in the same canonical review shape.
- [Prism](/docs/prism.md): Cross-source reputation and product reviews in one call.