// docs

Booking: Read reviews

Extracts hotel reviews from Booking with pagination, sorting and filter by period of the year.

booking.com.br:review · 5 credits per request

Standard credit cost. Your account pricing is shown in the sandbox.

HTTP request

cURL

curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://www.booking.com/hotel/br/iguassu-lofts.html",
  "target": "booking.com.br",
  "type": "review",
  "sort": "newest_first",
  "reviewPeriod": "dec_feb",
  "page": 1
}'

Keep your API key on your server. See the quickstart for authentication and response handling.

MCP request

The hosted MCP tool fixes target and type for this operation. Its remaining arguments use the same input rules as Extract.

POST /v1/mcp · Bearer or X-API-Key authentication

booking_com_br_review · tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "booking_com_br_review",
    "arguments": {
      "url": "https://www.booking.com/hotel/br/iguassu-lofts.html",
      "sort": "newest_first",
      "reviewPeriod": "dec_feb",
      "page": 1,
      "executionId": "exec_example_123"
    }
  }
}

Supported inputs

Conditional fields depend on the alternatives and constraints in the rule column. Fields marked unsupported are omitted.

Field	Type	Requirement	Rule	Default	Example
url URL extraction target. For some PLPs it can be omitted when API assembles URL from other fields.	string (URL)	Required	Mandatory for Booking Review.	-	https://www.booking.com/hotel/br/iguassu-lofts.html
sort Ordering for VivaReal, Chaves na Mão, OLX and Webmotors PLP, Booking Review and Hotels Review. VivaReal: relevance/date/price/biggest_price/biggest_area. Webmotors: relevance/price/biggest_price/year_desc/mileage_asc. OLX: relevance/date/price/biggest_price/price_relevance. Booking/Hotels Review: most_relevant/newest_first/oldest_first/score_desc/score_asc.	"relevance" \| "date" \| "price" \| "biggest_price" \| "biggest_area" \| "price_relevance" \| "most_relevant" \| "newest_first" \| "oldest_first" \| "score_desc" \| "score_asc" \| "year_desc" \| "mileage_asc"	Optional	Ordering of reviews: most_relevant, newest_first, oldest_first, score_desc or score_asc.	newest_first	newest_first
reviewPeriod User-friendly filter for the period of the year in Booking Review. API also accepts aliases such as Dec-Feb, Mar-May, Jun-Aug, Sep-Nov and the internal codes _12_02, _03_05, _06_08, _09_11.	"dec_feb" \| "mar_may" \| "jun_aug" \| "sep_nov"	Optional	User-friendly filter by review period: dec_feb, mar_may, jun_aug or sep_nov. It also accepts aliases such as Dec-Feb/Mar-May and the internal codes of Booking.	without filter	dec_feb
target Target source for extraction.	enum	Required	Always mandatory in the payload and must match the operation.	-	booking.com.br
type Extraction type: pdp, idp, plp, ilp, quote, review or places.	enum	Required	Always mandatory in the payload and must match the operation.	-	review
page Pagination. In PLP, including Trivago, and in Reclame AQUI ILP starts in 1; in review (MercadoLivre, Booking and Hotels) starts in 0. The Reclame AQUI ILP even accepts the page 100.	integer	Optional	Supported for review; starts at 0.	0	1

Request examples

Reviews by URL with period filter

Review page with sort, pagination and user-friendly filter by period of the year.

Reviews by URL with period filter

{
  "url": "https://www.booking.com/hotel/br/iguassu-lofts.html",
  "target": "booking.com.br",
  "type": "review",
  "sort": "newest_first",
  "reviewPeriod": "dec_feb",
  "page": 1
}

Response schema

Leaf paths and expected types. Field names and enum values are part of the API contract.

responseSchema

{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
  "data.source": "string",
  "data.type": "string",
  "data.parser": "\"1.0.0\"",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.hotelId": "number",
  "data.ufi": "number",
  "data.hotelCountryCode": "string",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.sort": "string",
  "data.reviewPeriod": "string | null",
  "data.timeOfYearCode": "string | null",
  "data.availableSorters[].name": "string",
  "data.availableSorters[].value": "string",
  "data.availableReviewPeriods[].name": "string",
  "data.availableReviewPeriods[].reviewPeriod": "string | null",
  "data.availableReviewPeriods[].timeOfYearCode": "string",
  "data.availableReviewPeriods[].count": "number",
  "data.availableReviewPeriods[].selected": "boolean",
  "data.ratingScores[].name": "string",
  "data.ratingScores[].translation": "string",
  "data.ratingScores[].value": "number",
  "data.totalReviews": "number",
  "data.hasNextPage": "boolean",
  "data.nextPage": "number",
  "data.nextPageUrl": "string",
  "data.reviews[].reviewId": "string",
  "data.reviews[].reviewUrl": "string",
  "data.reviews[].reviewedDate": "string",
  "data.reviews[].reviewedDateIso": "string",
  "data.reviews[].reviewScore": "number",
  "data.reviews[].helpfulVotesCount": "number",
  "data.reviews[].title": "string",
  "data.reviews[].positiveText": "string",
  "data.reviews[].negativeText": "string",
  "data.reviews[].textLanguage": "string",
  "data.reviews[].textTrivialFlag": "string",
  "data.reviews[].isTranslatable": "boolean",
  "data.reviews[].isApproved": "boolean",
  "data.reviews[].partnerReply": "string",
  "data.reviews[].guest.username": "string",
  "data.reviews[].guest.countryCode": "string",
  "data.reviews[].guest.countryName": "string",
  "data.reviews[].guest.guestType": "string",
  "data.reviews[].booking.customerType": "string",
  "data.reviews[].booking.roomTypeName": "string",
  "data.reviews[].booking.checkinDate": "string (YYYY-MM-DD)",
  "data.reviews[].booking.checkoutDate": "string (YYYY-MM-DD)",
  "data.reviews[].booking.numNights": "number",
  "data.reviews[].photos[].id": "string",
  "data.reviews[].photos[].kind": "string",
  "data.reviews[].photos[].urls[].size": "string",
  "data.reviews[].photos[].urls[].url": "string"
}

Example response

Illustrative response. Product names, reviews and other source content retain their original language. Missing and null values do not imply zero stock, free shipping or zero reviews.

responseExample

{
  "requestId": "88888888-1111-4111-8111-888888888888",
  "executionId": "88888888-2222-4222-8222-888888888888",
  "data": {
    "source": "booking.com.br",
    "type": "review",
    "parser": "1.0.0",
    "url": "https://www.booking.com/hotel/br/iguassu-lofts.html?checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL#tab-reviews",
    "requestUrl": "https://www.booking.com/hotel/br/iguassu-lofts.html?checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL#tab-reviews",
    "extractedAt": "2026-03-05T15:10:00.000Z",
    "hotelId": 13224605,
    "ufi": -643720,
    "hotelCountryCode": "br",
    "page": 1,
    "resultsPerPage": 10,
    "offset": 10,
    "sort": "NEWEST_FIRST",
    "reviewPeriod": "dec_feb",
    "timeOfYearCode": "_12_02",
    "availableSorters": [
      {
        "name": "Most relevant",
        "value": "MOST_RELEVANT"
      },
      {
        "name": "Newest first",
        "value": "NEWEST_FIRST"
      }
    ],
    "availableReviewPeriods": [
      {
        "name": "Dec to Feb",
        "reviewPeriod": "dec_feb",
        "timeOfYearCode": "_12_02",
        "count": 48,
        "selected": true
      },
      {
        "name": "Mar to May",
        "reviewPeriod": "mar_may",
        "timeOfYearCode": "_03_05",
        "count": 52,
        "selected": false
      }
    ],
    "ratingScores": [
      {
        "name": "Cleanliness",
        "translation": "Limpeza",
        "value": 9.3
      }
    ],
    "totalReviews": 217,
    "hasNextPage": true,
    "nextPage": 2,
    "nextPageUrl": "https://www.booking.com/hotel/br/iguassu-lofts.html?checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL&review_page=2&review_sort=newest_first#tab-reviews",
    "reviews": [
      {
        "reviewId": "88997766",
        "reviewUrl": "https://www.booking.com/reviews/br/hotel/iguassu-lofts?review_id=88997766",
        "reviewedDate": "1770981577",
        "reviewedDateIso": "2026-02-13T17:59:37.000Z",
        "reviewScore": 10,
        "helpfulVotesCount": 3,
        "title": "Excelente estadia",
        "positiveText": "Tudo perfeito.",
        "negativeText": "Nada a declarar.",
        "textLanguage": "pt",
        "textTrivialFlag": "NONE",
        "isTranslatable": true,
        "isApproved": true,
        "partnerReply": "Obrigado pela visita!",
        "guest": {
          "username": "Felipe",
          "avatarUrl": "https://cf.bstatic.com/profile.jpg",
          "countryCode": "br",
          "countryName": "Brazil",
          "avatarColor": "#1f2937",
          "showCountryFlag": true,
          "anonymous": false,
          "guestType": "Casal"
        },
        "booking": {
          "customerType": "couple",
          "roomId": "12345",
          "roomTypeId": "888",
          "roomTypeName": "Quarto Deluxe",
          "checkinDate": "2026-03-13",
          "checkoutDate": "2026-03-14",
          "numNights": 1,
          "stayStatus": "stayed"
        },
        "photos": [
          {
            "id": "1",
            "kind": "ROOM",
            "urls": [
              {
                "size": "SMALL",
                "url": "https://cf.bstatic.com/photo-small.jpg"
              },
              {
                "size": "LARGE",
                "url": "https://cf.bstatic.com/photo-large.jpg"
              }
            ]
          }
        ]
      }
    ]
  }
}

Complete field reference

Path	Type	Description	Example
data.availableReviewPeriods[].count	number	Number of reviews available in this range.	48
data.availableReviewPeriods[].name	string	Label returned by Booking for the period range.	Dec to Feb
data.availableReviewPeriods[].reviewPeriod	string \| null	Equivalent friendly value for use on API, when known.	dec_feb
data.availableReviewPeriods[].selected	boolean	Indicates whether this range was selected in the request.	true
data.availableReviewPeriods[].timeOfYearCode	string	Raw filter code timeOfYear returned by Booking.	_12_02
data.availableSorters[].name	string	Field data.availableSorters[].name returned in the response payload.	Most relevant
data.availableSorters[].value	string	Field data.availableSorters[].value returned in the response payload.	MOST_RELEVANT
data.extractedAt	string (iso datetime)	data.extractedAt field returned in the response payload.	2026-03-05T15:10:00.000Z
data.hasNextPage	boolean	Field data.hasNextPage returned in the response payload.	true
data.hotelCountryCode	string	Field data.hotelCountryCode returned in the response payload.	br
data.hotelId	number	Field data.hotelId returned in the response payload.	13224605
data.nextPage	number	Field data.nextPage returned in the response payload.	2
data.nextPageUrl	string	Field data.nextPageUrl returned in the response payload.	https://www.booking.com/hotel/br/iguassu-lofts.html?checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL&review_page=2&review_sort=newest_first#tab-reviews
data.offset	number	Field data.offset returned in the response payload.	10
data.page	number	Field data.page returned in the response payload.	1
data.parser	"1.0.0"	Stable version of the API response format.	1.0.0
data.ratingScores[].name	string	data.ratingScores[].name field returned in the response payload.	Cleanliness
data.ratingScores[].translation	string	data.ratingScores[].translation field returned in the response payload.	Limpeza
data.ratingScores[].value	number	Field data.ratingScores[].value returned in the response payload.	9.3
data.requestUrl	string	Same value as `data.url`; never exposes the queried internal endpoint.	https://www.booking.com/hotel/br/iguassu-lofts.html?checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL#tab-reviews
data.resultsPerPage	number	Field data.resultsPerPage returned in the response payload.	10
data.reviewPeriod	string \| null	Friendly period effectively applied to the reviews filter.	dec_feb
data.reviews[].booking.checkinDate	string (YYYY-MM-DD)	Field data.reviews[].booking.checkinDate returned in the response payload.	2026-03-13
data.reviews[].booking.checkoutDate	string (YYYY-MM-DD)	Field data.reviews[].booking.checkoutDate returned in the response payload.	2026-03-14
data.reviews[].booking.customerType	string	Field data.reviews[].booking.customerType returned in the response payload.	couple
data.reviews[].booking.numNights	number	Field data.reviews[].booking.numNights returned in the response payload.	1
data.reviews[].booking.roomTypeName	string	Field data.reviews[].booking.roomTypeName returned in the response payload.	Quarto Deluxe
data.reviews[].guest.countryCode	string	data.reviews[].guest.countryCode field returned in the response payload.	br
data.reviews[].guest.countryName	string	Field data.reviews[].guest.countryName returned in the response payload.	Brazil
data.reviews[].guest.guestType	string	Field data.reviews[].guest.guestType returned in the response payload.	Casal
data.reviews[].guest.username	string	Field data.reviews[].guest.username returned in the response payload.	Felipe
data.reviews[].helpfulVotesCount	number	Field data.reviews[].helpfulVotesCount returned in the response payload.	3
data.reviews[].isApproved	boolean	Field data.reviews[].isApproved returned in the response payload.	true
data.reviews[].isTranslatable	boolean	Field data.reviews[].isTranslatable returned in the response payload.	true
data.reviews[].negativeText	string	Field data.reviews[].negativeText returned in the response payload.	Nada a declarar.
data.reviews[].partnerReply	string	Field data.reviews[].partnerReply returned in the response payload.	Obrigado pela visita!
data.reviews[].photos[].id	string	Field data.reviews[].photos[].id returned in the response payload.	1
data.reviews[].photos[].kind	string	data.reviews[].photos[].kind field returned in the response payload.	ROOM
data.reviews[].photos[].urls[].size	string	Field data.reviews[].photos[].urls[].size returned in the response payload.	SMALL
data.reviews[].photos[].urls[].url	string	Field data.reviews[].photos[].urls[].url returned in the response payload.	https://cf.bstatic.com/photo-small.jpg
data.reviews[].positiveText	string	Field data.reviews[].positiveText returned in the response payload.	Tudo perfeito.
data.reviews[].reviewedDate	string	Field data.reviews[].reviewedDate returned in the response payload.	1770981577
data.reviews[].reviewedDateIso	string	Field data.reviews[].reviewedDateIso returned in the response payload.	2026-02-13T17:59:37.000Z
data.reviews[].reviewId	string	Field data.reviews[].reviewId returned in the response payload.	88997766
data.reviews[].reviewScore	number	Field data.reviews[].reviewScore returned in the response payload.	10
data.reviews[].reviewUrl	string	Field data.reviews[].reviewUrl returned in the response payload.	https://www.booking.com/reviews/br/hotel/iguassu-lofts?review_id=88997766
data.reviews[].textLanguage	string	Field data.reviews[].textLanguage returned in the response payload.	pt
data.reviews[].textTrivialFlag	string	Field data.reviews[].textTrivialFlag returned in the response payload.	NONE
data.reviews[].title	string	Field data.reviews[].title returned in the response payload.	Excelente estadia
data.sort	string	data.sort field returned in the response payload.	NEWEST_FIRST
data.source	string	Field data.source returned in the response payload.	booking.com.br
data.timeOfYearCode	string \| null	Booking internal code used in the timeOfYear filter.	_12_02
data.totalReviews	number	Field data.totalReviews returned in the response payload.	217
data.type	string	Field data.type returned in the response payload.	review
data.ufi	number	Field data.ufi returned in the response payload.	-643720
data.url	string	Field data.url returned in the response payload.	https://www.booking.com/hotel/br/iguassu-lofts.html?checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL#tab-reviews
executionId	string (uuid)	Field executionId returned in the response payload.	88888888-2222-4222-8222-888888888888
notFound	boolean (optional; true when the upstream entity was not found and data is null)	Present and true when the upstream entity was not found. In this case data is null and the request still completes successfully.	N/A
requestId	string (uuid)	Field requestId returned in the response payload.	88888888-1111-4111-8111-888888888888

Errors and missing data

When supported by this operation, an entity not found upstream can return HTTP 200 with data: null and notFound: true. Check the documented response fields before interpreting an empty result. Source-specific behavior and exceptions are described above.

HTTP status	Error code	Meaning
400	`INVALID_PAYLOAD`	Invalid JSON or a request that violates the documented validation rules.
401	`UNAUTHORIZED`	Missing authorization or an invalid API key or token.
402	`INSUFFICIENT_CREDITS`	The account has insufficient credits for this operation.
403	`FORBIDDEN`	The account does not have access, or the API is temporarily disabled.
409	`EXECUTION_CONFLICT`	The execution identifier conflicts with an incompatible execution state.
429	`RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS`	A rate limit or simultaneous request limit was exceeded.
5xx	`UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERROR`	An upstream, worker or gateway failure. Failed requests follow the platform refund policy.

Booking: Read reviews

HTTP request

MCP request

Supported inputs

Request examples

Reviews by URL with period filter

Response schema

Example response

Complete field reference

Errors and missing data

Other Booking operations