GeckoAPI
Entrar Agendar uma demo

// docs

Booking Review

Extrai avaliacoes de hotel no Booking com paginação, ordenacao e filtro por periodo do ano.

Nota importante: alguns campos podem retornar null em produção, dependendo da página de origem. Nesta documentação, os exemplos de output são preenchidos intencionalmente com valores não nulos para facilitar integração.

Chamada HTTP

cURL 
curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer SUA_CHAVE" \
  -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
}'

Chamada MCP

A mesma seam também aparece no MCP hospedado como uma tool dedicada. Os argumentos reaproveitam os campos do extract, mas target e type já ficam fixos pela tool.

Ver guia completo do MCP

Endpoint

POST /v1/mcp

Tool name

booking_com_br_review

Auth

Bearer ou X-API-Key

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"
    }
  }
}

Possibilidades de input

Campos suportados nesta API do POST /v1/extract, com regras específicas de obrigatoriedade e condicionais.

Campo Tipo Status Regra Default Exemplo
url
URL alvo da extração. Para alguns PLPs pode ser omitida quando a API monta a URL a partir de outros campos.
 string (URL) Obrigatório Obrigatorio para Booking Review. - https://www.mercadolivre.com.br/p/MLB123456
sort
Ordenacao para OLX PLP, Booking Review e Hoteis Review. OLX: relevance/date/price/biggest_price/price_relevance. Booking/Hoteis Review: most_relevant/newest_first/oldest_first/score_desc/score_asc.
 "relevance" | "date" | "price" | "biggest_price" | "price_relevance" | "most_relevant" | "newest_first" | "oldest_first" | "score_desc" | "score_asc" Opcional Ordenacao das reviews: most_relevant, newest_first, oldest_first, score_desc ou score_asc. newest_first date
reviewPeriod
Filtro amigavel para o periodo do ano em Booking Review. A API tambem aceita aliases como dez-fev, mar-mai, jun-ago, set-nov e os codigos internos _12_02, _03_05, _06_08, _09_11.
 "dec_feb" | "mar_may" | "jun_aug" | "sep_nov" Opcional Filtro amigavel por periodo das reviews: dec_feb, mar_may, jun_aug ou sep_nov. Tambem aceita aliases como dez-fev/mar-mai e os codigos internos do Booking. sem filtro dec_feb
target
Fonte alvo da extração.
 enum Obrigatório Sempre obrigatorio no payload e deve combinar com o seam. - mercadolivre.com.br
type
Tipo da extração: pdp, idp, plp, review ou places.
 enum Obrigatório Sempre obrigatorio no payload e deve combinar com o seam. - pdp
page
Paginacao. Em PLP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0.
 integer Opcional Suportado para review; inicia em 0. 0 2

Exemplos de request

Reviews por URL com filtro de periodo

Pagina de reviews com sort, paginação e filtro amigavel por periodo do ano.

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

Schema de response (leaf paths)

Mapa de paths de saída com tipo esperado para esta API.

responseSchema 
{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "data.source": "string",
  "data.type": "string",
  "data.parser": "string",
  "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"
}

Exemplo de response

responseExample 
{
  "requestId": "88888888-1111-4111-8111-888888888888",
  "executionId": "88888888-2222-4222-8222-888888888888",
  "data": {
    "source": "booking.com.br",
    "type": "review",
    "parser": "graphql_review_list",
    "url": "https://www.booking.com/hotel/br/iguassu-lofts.html?checkin=2026-04-14&checkout=2026-04-15&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL#tab-reviews",
    "requestUrl": "https://www.booking.com/dml/graphql?aid=381641&lang=pt-br&checkin=2026-04-14&checkout=2026-04-15&group_adults=2&group_children=0&no_rooms=1",
    "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-04-14&checkout=2026-04-15&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"
              }
            ]
          }
        ]
      }
    ]
  }
}

Referência completa de campos

Path Tipo Descrição Exemplo
data.availableReviewPeriods[].count number Quantidade de reviews disponiveis nessa faixa. 48
data.availableReviewPeriods[].name string Label retornado pelo Booking para a faixa de periodo. Dec to Feb
data.availableReviewPeriods[].reviewPeriod string | null Valor amigavel equivalente para uso na API, quando conhecido. dec_feb
data.availableReviewPeriods[].selected boolean Indica se essa faixa foi a selecionada na requisicao. true
data.availableReviewPeriods[].timeOfYearCode string Codigo bruto do filtro timeOfYear retornado pelo Booking. _12_02
data.availableSorters[].name string Campo data.availableSorters[].name retornado no payload de resposta. Most relevant
data.availableSorters[].value string Campo data.availableSorters[].value retornado no payload de resposta. MOST_RELEVANT
data.extractedAt string (iso datetime) Campo data.extractedAt retornado no payload de resposta. 2026-03-05T15:10:00.000Z
data.hasNextPage boolean Campo data.hasNextPage retornado no payload de resposta. true
data.hotelCountryCode string Campo data.hotelCountryCode retornado no payload de resposta. br
data.hotelId number Campo data.hotelId retornado no payload de resposta. 13224605
data.nextPage number Campo data.nextPage retornado no payload de resposta. 2
data.nextPageUrl string Campo data.nextPageUrl retornado no payload de resposta. https://www.booking.com/hotel/br/iguassu-lofts.html?checkin=2026-04-14&checkout=2026-04-15&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 Campo data.offset retornado no payload de resposta. 10
data.page number Campo data.page retornado no payload de resposta. 1
data.parser string Campo data.parser retornado no payload de resposta. graphql_review_list
data.ratingScores[].name string Campo data.ratingScores[].name retornado no payload de resposta. Cleanliness
data.ratingScores[].translation string Campo data.ratingScores[].translation retornado no payload de resposta. Limpeza
data.ratingScores[].value number Campo data.ratingScores[].value retornado no payload de resposta. 9.3
data.requestUrl string Campo data.requestUrl retornado no payload de resposta. https://www.booking.com/dml/graphql?aid=381641&lang=pt-br&checkin=2026-04-14&checkout=2026-04-15&group_adults=2&group_children=0&no_rooms=1
data.resultsPerPage number Campo data.resultsPerPage retornado no payload de resposta. 10
data.reviewPeriod string | null Periodo amigavel efetivamente aplicado no filtro de reviews. dec_feb
data.reviews[].booking.checkinDate string (YYYY-MM-DD) Campo data.reviews[].booking.checkinDate retornado no payload de resposta. 2026-03-13
data.reviews[].booking.checkoutDate string (YYYY-MM-DD) Campo data.reviews[].booking.checkoutDate retornado no payload de resposta. 2026-03-14
data.reviews[].booking.customerType string Campo data.reviews[].booking.customerType retornado no payload de resposta. couple
data.reviews[].booking.numNights number Campo data.reviews[].booking.numNights retornado no payload de resposta. 1
data.reviews[].booking.roomTypeName string Campo data.reviews[].booking.roomTypeName retornado no payload de resposta. Quarto Deluxe
data.reviews[].guest.countryCode string Campo data.reviews[].guest.countryCode retornado no payload de resposta. br
data.reviews[].guest.countryName string Campo data.reviews[].guest.countryName retornado no payload de resposta. Brazil
data.reviews[].guest.guestType string Campo data.reviews[].guest.guestType retornado no payload de resposta. Casal
data.reviews[].guest.username string Campo data.reviews[].guest.username retornado no payload de resposta. Felipe
data.reviews[].helpfulVotesCount number Campo data.reviews[].helpfulVotesCount retornado no payload de resposta. 3
data.reviews[].isApproved boolean Campo data.reviews[].isApproved retornado no payload de resposta. true
data.reviews[].isTranslatable boolean Campo data.reviews[].isTranslatable retornado no payload de resposta. true
data.reviews[].negativeText string Campo data.reviews[].negativeText retornado no payload de resposta. Nada a declarar.
data.reviews[].partnerReply string Campo data.reviews[].partnerReply retornado no payload de resposta. Obrigado pela visita!
data.reviews[].photos[].id string Campo data.reviews[].photos[].id retornado no payload de resposta. 1
data.reviews[].photos[].kind string Campo data.reviews[].photos[].kind retornado no payload de resposta. ROOM
data.reviews[].photos[].urls[].size string Campo data.reviews[].photos[].urls[].size retornado no payload de resposta. SMALL
data.reviews[].photos[].urls[].url string Campo data.reviews[].photos[].urls[].url retornado no payload de resposta. https://cf.bstatic.com/photo-small.jpg
data.reviews[].positiveText string Campo data.reviews[].positiveText retornado no payload de resposta. Tudo perfeito.
data.reviews[].reviewedDate string Campo data.reviews[].reviewedDate retornado no payload de resposta. 1770981577
data.reviews[].reviewedDateIso string Campo data.reviews[].reviewedDateIso retornado no payload de resposta. 2026-02-13T17:59:37.000Z
data.reviews[].reviewId string Campo data.reviews[].reviewId retornado no payload de resposta. 88997766
data.reviews[].reviewScore number Campo data.reviews[].reviewScore retornado no payload de resposta. 10
data.reviews[].reviewUrl string Campo data.reviews[].reviewUrl retornado no payload de resposta. https://www.booking.com/reviews/br/hotel/iguassu-lofts?review_id=88997766
data.reviews[].textLanguage string Campo data.reviews[].textLanguage retornado no payload de resposta. pt
data.reviews[].textTrivialFlag string Campo data.reviews[].textTrivialFlag retornado no payload de resposta. NONE
data.reviews[].title string Campo data.reviews[].title retornado no payload de resposta. Excelente estadia
data.sort string Campo data.sort retornado no payload de resposta. NEWEST_FIRST
data.source string Campo data.source retornado no payload de resposta. booking.com.br
data.timeOfYearCode string | null Codigo interno do Booking usado no filtro timeOfYear. _12_02
data.totalReviews number Campo data.totalReviews retornado no payload de resposta. 217
data.type string Campo data.type retornado no payload de resposta. review
data.ufi number Campo data.ufi retornado no payload de resposta. -643720
data.url string Campo data.url retornado no payload de resposta. https://www.booking.com/hotel/br/iguassu-lofts.html?checkin=2026-04-14&checkout=2026-04-15&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL#tab-reviews
executionId string (uuid) Campo executionId retornado no payload de resposta. 88888888-2222-4222-8222-888888888888
requestId string (uuid) Campo requestId retornado no payload de resposta. 88888888-1111-4111-8111-888888888888

Erros comuns

Status errorCode Quando acontece
400 INVALID_PAYLOAD JSON inválido ou violação das regras de validação do payload.
401 UNAUTHORIZED Header Authorization ausente ou token/chave inválida.
402 INSUFFICIENT_CREDITS Saldo de créditos insuficiente para a API solicitada.
403 FORBIDDEN Usuário sem acesso ou API temporariamente desabilitada.
409 EXECUTION_CONFLICT executionId conflita com uma execução em estado incompatível.
429 RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS Limite de taxa ou limite de requisições em voo excedido.
5xx UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_INVOCATION_FAILED / WORKER_FUNCTION_ERROR / WORKER_INVALID_RESPONSE / INTERNAL_ERROR Falha de servidor no worker, provider/proxy ou gateway. Nesses casos os créditos são estornados automaticamente.
WhatsApp