# Tripadvisor (/docs/tripadvisor)



Tripadvisor [#tripadvisor]

Search Tripadvisor for businesses and places — restaurants, hotels, attractions — and pull their traveler reviews behind the unified SocialCrawl schema.

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

Getting Started [#getting-started]

It's 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`. Repeated searches may use the 2-minute endpoint cache and repeated review requests the 5-minute cache; cache hits cost 0 credits, and `Cache-Control: no-cache` requests a billed refresh.

```bash
# 1. Find the place — note that the query parameter is `q`, not `query`
curl "https://www.socialcrawl.dev/v1/tripadvisor/search?q=pizza%20restaurant&location=New%20York,New%20York,United%20States&depth=30" \
  -H "x-api-key: sc_your_api_key_here"

# 2. Its traveler reviews, using the url_path from step 1 (no leading slash)
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: sc_your_api_key_here"
```

* **`GET /v1/tripadvisor/search`** (1cr) takes `q` and returns places — restaurants, hotels, attractions — each with name, category, star rating, total review count, and the `url_path` that identifies it. `location` scopes it, `language` narrows the result language, and `depth` is the result count in multiples of 30 (default 30, max 60 on this synchronous endpoint).
* **`GET /v1/tripadvisor/reviews`** (1cr) takes that `url_path` verbatim, without a leading slash, and returns traveler reviews: star rating, title, full text, reviewer, attached photos, management `responses[]`, language, and publish date. `depth` is in multiples of 10 (default 10, max 30).

Both endpoints are powered by DataForSEO: search returns the first-class canonical `Place` object, reviews returns the shared `Review` object (the same shape as any other reviews source), so your code reads Tripadvisor exactly like it reads Amazon, Google Shopping, or Trustpilot.

<Callout type="warn">
  `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.
</Callout>

Endpoints [#endpoints]

<PlatformEndpoints platform="tripadvisor" />

Notes [#notes]

* All endpoints use `GET` method with query parameters
* Authentication via `x-api-key` header
* Responses follow the unified SocialCrawl schema (`PlaceList` for search, `ReviewList` for reviews)
* **Two-step flow:** `search` returns each place's `url_path` (the chaining key); pass it to `reviews`. The place `id` and absolute `url` are derived from that `url_path`.
* `search` is location-bound — pass `location` (e.g. `New York,New York,United States`); it defaults to the United States
* Reviews carry the star rating, full text, reviewer profile, attached photos, owner/management `responses[]`, and — because Tripadvisor auto-translates — a `translated` flag plus the `original_language`
* Filter reviews by traveler `rating`, `visit_type`, or a keyword (`search_reviews_keyword`); sort by `most_recent` or `detailed_reviews`. The synchronous endpoint caps `depth` at 30 (deeper history is a future async surface)
* Neither endpoint paginates — `depth` is the only size control on both
* A cold call takes roughly 15-45 seconds because the upstream is a task-based API whose async lifecycle we settle server-side; repeats serve from cache. Set client timeouts accordingly
* A place with no matching reviews returns `404`, refunded automatically