Skip to content
Docs

Tripadvisor reviews

Tripadvisor reviews for one hotel, restaurant or attraction.

POST/v1/ota/tripadvisor/reviews
1 creditTry itTripadvisor API overview →

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

POSThttps://api.scrapercompany.com/v1/ota/tripadvisor/reviews

Authenticate with your API key in the x-api-key header (see Authentication).

Run this request on your own API key from this page, with the values you type. Signed out? Sign in or get an API key.

Body

JSON object. Unknown fields are rejected with 422.

  • location_idstring | nullmin 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.

  • urlstring | nullmin 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.

  • namestring | nullmin 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.

  • citystringdefault max length 200

    With name: the city, sent with the name and used to rank same-name places elsewhere lower.

  • typesarray of string | nullmin items 1, max items 3

    With name: kinds of place to search (hotel, restaurant, attraction; default all three).

  • limitintegerdefault 10min 1, max 30

    Reviews per page (standard paging only). The backend returns 20 per upstream page; limit=30 fetches 2 pages.

  • offsetintegerdefault 0min 0

    Starting row (standard paging). Cannot be combined with max_reviews.

  • max_reviewsinteger | nullmin 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_datestring | nullpattern ^\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.

  • sortstring | null

    newest (default; the owner's pinned review sits near the top) or detailed. since_date needs newest.

    One ofnewestdetailed

  • ratingsarray of integer | nullmin items 1, max items 5

    Only these ratings (1-5); total counts matches.

  • traveler_typesarray of string | nullmin items 1, max items 5

    Only these traveler types.

  • keywordstring | nullmin length 2, max length 100

    Only reviews mentioning this text.

  • languagestring | nullpattern ^[a-z]{2,3}(?:[-_][A-Za-z]{2,4})?$

    Only reviews in this language (en, fr, zh_TW).

Example request

curl -X POST "https://api.scrapercompany.com/v1/ota/tripadvisor/reviews" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

200 — Tripadvisor reviews: standard page or bulk fetch with deduplication. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

200 response
{
  "source": "tripadvisor",
  "property_id": "208453",
  "total": 9023,
  "offset": 0,
  "limit": 500,
  "rating_scale": 5,
  "count": 500,
  "pages_fetched": 25,
  "warnings": [],
  "reviews": [
    {
      "source": "tripadvisor",
      "review_id": "1079997723",
      "rating": 5,
      "title": "Hilton times square fab hotel",
      "text": "if you are coming to New York hilton times square is the best for location . large spacious rooms great service , friendly staff , highly recommend",
      "date": "2026-09-30",
      "author": "Sue B",
      "trip_type": "FAMILY",
      "stay_date": "2026-09",
      "management_reply": "Dear Gayatri, it's a privilege to learn about your memorable stay with us!",
      "language": "en",
      "helpful_votes": 0,
      "url": "/ShowUserReviews-g60763-d208453-r1079997723-Hilton_New_York_Times_Square-New_York_City_New_York.html",
      "submitted_at": "2026-09-30T14:02:11.120Z",
      "reviewer": {
        "id": "B48511BF476A489410637C11C2E7C9F9",
        "username": "sueb",
        "profile_url": "https://www.tripadvisor.com/Profile/sueb",
        "verified": false,
        "contributions": 12,
        "helpful_votes": 3,
        "hometown": "Leeds, United Kingdom"
      },
      "sub_ratings": {
        "value": 4,
        "rooms": 5,
        "location": 5,
        "cleanliness": 5,
        "service": 5,
        "sleep_quality": 4
      },
      "photos": [
        {
          "id": "888100222",
          "url": "https://dynamic-media-cdn.tripadvisor.com/media/photo-o/34/ef/55/7e/caption.jpg?w=3024&h=4032&s=1",
          "url_template": "https://dynamic-media-cdn.tripadvisor.com/media/photo-o/34/ef/55/7e/caption.jpg?w={width}&h={height}&s=1",
          "width": 3024,
          "height": 4032
        }
      ],
      "photo_count": 1,
      "machine_translated": false,
      "original_language": "en",
      "tips": [
        "Ask for a high floor facing Broadway."
      ],
      "pinned": false,
      "management_reply_role": "Guest Relations"
    },
    {
      "source": "tripadvisor",
      "review_id": "1076579565",
      "rating": 4,
      "title": "Good location",
      "text": "Rooms were comfortable, staff friendly.",
      "date": "2026-09-28",
      "author": "Nina",
      "trip_type": "BUSINESS",
      "stay_date": "2026-09",
      "language": "en",
      "helpful_votes": 2,
      "url": "/ShowUserReviews-g60763-d208453-r1076579565-Hilton_New_York_Times_Square-New_York_City_New_York.html"
    }
  ],
  "provenance": {
    "schema_version": 1,
    "observation_id": "rateobs_f6eb31f7144bb7dc40e0ceefa63b306d",
    "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
    "observed_at": "2026-08-07T01:23:45.678Z",
    "source": "tripadvisor",
    "source_kind": "reviews",
    "source_property_id": "208453",
    "price_basis": "unknown",
    "derivation": "upstream"
  },
  "resolved": {
    "location_id": "208453",
    "input": "https://www.tripadvisor.com/Hotel_Review-g60763-d208453-Reviews-Hilton_New_York_Times_Square-New_York_City_New_York.html",
    "input_kind": "url",
    "geo_id": "60763",
    "type": "hotel",
    "url": "https://www.tripadvisor.com/Hotel_Review-g60763-d208453-Reviews-Hilton_New_York_Times_Square-New_York_City_New_York.html"
  },
  "elapsed_s": 0.412,
  "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
  "observed_at": "2026-08-07T01:23:45.678Z"
}

Errors

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

StatusMeaningRetry?
401Unauthorized

Missing or invalid API key.

{"detail":"missing or invalid API key"}
No, fix the request
402Payment Required

Not enough credits for this request: the account's credits mode is enforce (mode in GET /v1/billing) and the request costs more than the available credits. Nothing is run or charged.

{"detail":"insufficient credits: this request costs 5, 0 available. Credits renew 2026-11-01."}
No, fix the request
404Not Found

The property, stay, job or record was not found.

{"detail":"job not found"}
No, fix the request
422Unprocessable Content

Request validation failed. detail is a list of problems for schema errors, or a string for semantic checks performed by the endpoint.

{"detail":[{"loc":["body","name"],"msg":"Field required","type":"missing"}]}
No, fix the request
429Too Many Requests

Too many requests: the key's requests-per-minute limit was exceeded, or (in enforce credits mode) the plan's concurrent-request limit. No rate-limit or Retry-After headers are sent; back off and retry.

{"detail":"rate limit 60/min exceeded"}
Yes, with backoff
502Bad Gateway

The upstream source failed, blocked the request or returned an unusable answer. Safe to retry later; failed requests are not charged.

{"detail":"RuntimeError"}
Yes, with backoff

Try it

Press Try it above to run this request on your own key, with the values you type (sign in first). For a no-code walkthrough, use the workspace’s guided Try it.

  1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? start a free trial).
  2. Copy the cURL example above and run it in a terminal.

Credits

1 credit per successful call. Failed, blocked and empty results are free.

Questions about this page?

Send the page link and your question, and the team will answer.

Email support