# Tripadvisor reviews: `POST /v1/ota/tripadvisor/reviews`

Cost: 1 credit (1 (failed requests are free)). Docs: https://scrapercompany.com/docs/reference/tripadvisor-reviews

Tripadvisor reviews for one hotel, restaurant or attraction.

Name it by `location_id`, any Tripadvisor page `url`, or `name`
(+ `city`, narrowed by `types`); `resolved` echoes the location used
and its `type`. A name with no single
confident match answers 404 with `candidates`, uncharged.

**Standard paging**: one upstream page per request. Ratings are 0-5; each review keeps the author, trip type,
stay or visit date, management reply and language. Page by `offset += limit`.
Tripadvisor's backend serves 20 reviews per upstream page, and each page
is 1 credit: up to 20 reviews cost 1, `limit=30` 2 (settled for the
pages fetched).

**Bulk fetch**: set `max_reviews` to fetch multiple pages in parallel
(15 at a time by default). For a place with
~1700 reviews, bulk completes in ~6-7 seconds vs. 30+ seconds serial.
1 credit per upstream page that returned reviews (20 reviews each, so
1700 reviews = 85 credits), at most 200 pages (4,000 reviews) per request.
A request that returns no reviews is not charged.

**Incremental refresh**: set `since_date` (ISO date YYYY-MM-DD) to stop
fetching once older reviews are reached. For daily refresh, usually one
upstream page (20 reviews).

Results are deduplicated by `review_id` and returned newest first
(or Tripadvisor's "Detailed reviews" order with `sort=detailed`).
Warnings list any failed pages in bulk mode.

**Filters** (applied upstream, so `total` counts the matches and every
mode pages through matching reviews only): `ratings`,
`traveler_types`, `keyword`, `language`.

Each review also carries `reviewer` (id, username, profile URL,
contributions, helpful votes, verified, hometown), `photos`,
`sub_ratings`, `machine_translated` with `original_language`,
`submitted_at`, `tips`, `pinned` and `management_reply_role`.

Request body (JSON):

- `location_id` (string | null; optional; min length 1, max length 2048): Numeric Tripadvisor id (the digits after `-d` in a page URL), e.g. `17768161`. A Tripadvisor page URL is accepted here too.
- `url` (string | null; optional; min length 8, max length 2048): Any Tripadvisor page for the location, on any Tripadvisor domain: `Hotel_Review`, `Restaurant_Review`, `Attraction_Review`, `ShowUserReviews` ... The `-d` number is the location id and the `-g` number its geo id.
- `name` (string | null; optional; min length 2, max length 200): Place name, resolved with Tripadvisor's own search. Used only when one candidate clearly wins; otherwise the call answers 404 with up to five `candidates` to pick from. Add `city` for best results.
- `city` (string; optional; default ; max length 200): With `name`: the city, sent with the name and used to rank same-name places elsewhere lower.
- `types` (array of string | null; optional; min items 1, max items 3): With `name`: kinds of place to search (`hotel`, `restaurant`, `attraction`; default all three).
- `limit` (integer; optional; default 10; min 1, max 30): Reviews per page (standard paging only). The backend returns 20 per upstream page; limit=30 fetches 2 pages.
- `offset` (integer; optional; default 0; min 0): Starting row (standard paging). Cannot be combined with `max_reviews`.
- `max_reviews` (integer | null; optional; min 1): Bulk fetch: fetch up to this many reviews in parallel. When set, `offset` must be 0 and `limit` is ignored. Charged per upstream page (20 reviews each).
- `since_date` (string | null; optional; pattern ^\d{4}-\d{2}-\d{2}$): Incremental fetch: stop once reviews older than this ISO date (YYYY-MM-DD) are reached. Combines with `max_reviews` or standard paging. For daily refresh, this usually costs just one upstream call.
- `sort` (string | null; optional; one of newest, detailed): `newest` (default; the owner's pinned review sits near the top) or `detailed`. `since_date` needs `newest`.
- `ratings` (array of integer | null; optional; min items 1, max items 5): Only these ratings (1-5); `total` counts matches.
- `traveler_types` (array of string | null; optional; min items 1, max items 5): Only these traveler types.
- `keyword` (string | null; optional; min length 2, max length 100): Only reviews mentioning this text.
- `language` (string | null; optional; pattern ^[a-z]{2,3}(?:[-_][A-Za-z]{2,4})?$): Only reviews in this language (`en`, `fr`, `zh_TW`).

Base URL: `https://api.scrapercompany.com`. Auth: send your key in the `x-api-key` header. A failed request (4xx or 5xx) or an empty result costs 0 credits.

- [Full API reference as one Markdown file](https://scrapercompany.com/llms-full.txt)
- [OpenAPI spec](https://scrapercompany.com/openapi.json)
