scraper
Back to API docs

Overview

  • Overview

SERP

  • POSTSERP

Core

  • POSTGeocode
  • POSTTranslate
  • POSTSearch
  • POSTVision
  • POSTPlaces Search
  • POSTPlace Details
  • POSTPlaces Nearby
  • POSTAutocomplete

Maps

  • POSTSearch
  • POSTPlace Details
  • POSTReviews

Hotels

  • POSTSearch
  • POSTDetail
  • POSTReviews
  • POSTPhotos

Flights

  • POSTOne-way Search
  • POSTCalendar
  • POSTExplore

Finance

  • POSTQuote
  • POSTFundamentals
  • POSTChart
  • POSTNews
  • POSTSearch
  • POSTEstimates
  • POSTEarnings

Hotel Reviews

2 credits

Get guest reviews for a hotel with sorting and search filters.

POST/api/v1/tools/google/hotels/reviews

Parameters

hotelUrlstring

An HTTPS Google Hotels entity URL with the path /travel/hotels/entity/{bookingToken}. The maximum length is 4,096 characters. Provide exactly one target: hotelUrl, bookingToken, or propertyId. The request body is strict. Unknown fields are rejected.

bookingTokenstring

The bookingToken from a Search result. This is the preferred target. It can contain letters, numbers, underscores, and hyphens. The maximum length is 2,048 characters. Provide exactly one target.

propertyIdstring

Deprecated input alias for bookingToken. The value must be a booking token even though this input is named propertyId. Provide exactly one target.

sortstring

The order: "most_helpful", "most_recent", "highest_score", or "lowest_score". The default is "most_helpful".

searchstring

Text to find in reviews. The API removes space at the start and end. The maximum length is 200 characters. An empty value is ignored.

maxReviewsinteger

The maximum number of reviews to return, from 1 to 1,000. The default is 40. The value cannot be more than your plan limit.

fieldsstring[]

Select result fields. Values must be unique. Use ["*"] alone for all supported fields. If you omit this parameter, the API returns these default fields: "source", "author", "rating", "maxRating", "text", "date", "reviewId", "subRatings", "highlights". Supported fields: "source", "author", "authorUrl", "avatarUrl", "rating", "maxRating", "text", "date", "reviewId", "reviewUrl", "subRatings", "photos", "highlights", "replyText".

Response Schema

dataobject

The Google Hotels reviews result.

reviewsobject[]

The selected fields for each unique review. Some optional values can be absent.

returnedCountnumber

The number of reviews in this response.

collectedCountnumber

The number of unique reviews collected before maxReviews is applied.

truncatedboolean

True when maxReviews limits the output or when later pagination stops after a non-timeout failure, an invalid page, a repeated token, or no progress. A request deadline returns HTTP 504.

metaobject

Request metadata.

toolstring

The tool name.

creditsUsednumber

The request cost. The value is 2.

requestIdstring

The unique request ID.

Request

curl -X POST https://scraper.run/api/v1/tools/google/hotels/reviews \
  -H "Authorization: Bearer sc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bookingToken": "ChkIq_atzbv20-8ZGg0vZy8xMXFoMzRoa3pfEAE",
    "sort": "most_recent",
    "maxReviews": 2,
    "fields": ["reviewId", "author", "rating", "text", "date"]
  }'

Response Example

{
  "data": {
    "reviews": [
      {
        "reviewId": "review_123",
        "author": "A. Guest",
        "rating": 5,
        "text": "A clean room and helpful staff.",
        "date": "2 weeks ago"
      }
    ],
    "returnedCount": 1,
    "collectedCount": 1,
    "truncated": false
  },
  "meta": {
    "tool": "google-hotels-reviews",
    "creditsUsed": 2,
    "requestId": "req_abc123"
  }
}