Skip to content
PT Start free

// docs

Booking: Search stays

Extracts accommodation listing (PLP) from Booking with pagination.

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

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

Try this operation 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 '{
  "target": "booking.com.br",
  "type": "plp",
  "keyword": "curitiba parana",
  "checkinDate": "2026-11-26",
  "checkoutDate": "2026-11-27",
  "numAdults": 2,
  "numChildren": 0,
  "numRooms": 1,
  "lang": "pt-br",
  "currency": "BRL",
  "page": 2
}'

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_plp · tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "booking_com_br_plp",
    "arguments": {
      "keyword": "curitiba parana",
      "checkinDate": "2026-11-26",
      "checkoutDate": "2026-11-27",
      "numAdults": 2,
      "numChildren": 0,
      "numRooms": 1,
      "lang": "pt-br",
      "currency": "BRL",
      "page": 2,
      "executionId": "exec_example_123"
    }
  }
}

Supported inputs

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

FieldTypeRequirementRuleDefaultExample
url
URL extraction target. For some PLPs it can be omitted when API assembles URL from other fields.
 string (URL) Optional Optional for PLP; gateway can assemble URL from keyword. - https://www.mercadolivre.com.br/p/MLB123456
keyword
Keyword for PLP searches. In Google Search it represents the query sent to Google; in Booking PLP is mandatory; in other PLPs it can replace URL.
 string Required Mandatory in Booking PLP. - curitiba parana
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. - plp
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 PLP; must be integer >= 1. - 2
checkinDate
Check-in date for Booking PDP/PLP, Hoteis.com PDP/PLP and Trivago PDP/PLP.
 string (YYYY-MM-DD) Required Mandatory for Booking; it must be > today. - 2026-11-26
checkoutDate
Checkout date for Booking PDP/PLP, Hoteis.com PDP/PLP and Trivago PDP/PLP. Must be greater than checkinDate.
 string (YYYY-MM-DD) Required Mandatory for Booking; must be > checkinDate. - 2026-11-27
numAdults
Quantity of adults for Booking, Airbnb, Hoteis.com, Trivago, Decolar, GOL, Azul, LATAM and Trip.com.
 integer (1-30) Optional Optional for Booking. 2 2
numChildren
Number of children for Booking, Hoteis.com, Trivago, Decolar, GOL, Azul, LATAM and Trip.com.
 integer (0-30) Optional Optional for Booking. 0 0
numRooms
Number of rooms for Booking, Hoteis.com PDP/PLP and Trivago PDP/PLP.
 integer (1-15) Optional Optional for Booking. 1 1
lang
Language for Booking and Trivago (backend default: pt-br).
 string (ll or ll-cc) Optional Optional for Booking. pt-br pt-br
currency
Currency for Booking, Trivago and Azul (backend default: BRL).
 string (ISO 4217) Optional Optional for Booking. BRL BRL

Request examples

PLP by keyword

Booking PLP requires keyword and dates.

PLP by keyword 
{
  "target": "booking.com.br",
  "type": "plp",
  "keyword": "curitiba parana",
  "checkinDate": "2026-11-26",
  "checkoutDate": "2026-11-27",
  "numAdults": 2,
  "numChildren": 0,
  "numRooms": 1,
  "lang": "pt-br",
  "currency": "BRL",
  "page": 2
}

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.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.keyword": "string",
  "data.query": "string",
  "data.checkinDate": "string (YYYY-MM-DD)",
  "data.checkoutDate": "string (YYYY-MM-DD)",
  "data.numAdults": "number",
  "data.numChildren": "number",
  "data.numRooms": "number",
  "data.lang": "string",
  "data.currency": "string",
  "data.destination.name": "string",
  "data.destination.countryCode": "string",
  "data.destination.destId": "number",
  "data.destination.destType": "string",
  "data.totalResults": "number",
  "data.primaryResults": "number",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.nextPage": "number",
  "data.nextPageUrl": "string",
  "data.items[].url": "string",
  "data.items[].propertyId": "number",
  "data.items[].pageName": "string",
  "data.items[].name": "string",
  "data.items[].address": "string",
  "data.items[].city": "string",
  "data.items[].countryCode": "string",
  "data.items[].latitude": "number",
  "data.items[].longitude": "number",
  "data.items[].distance": "string",
  "data.items[].distanceMeters": "number",
  "data.items[].thumbnail": "string",
  "data.items[].currency": "string",
  "data.items[].price": "number",
  "data.items[].regularPrice": "number",
  "data.items[].averagePricePerNight": "number",
  "data.items[].aggregateRating.rating": "number",
  "data.items[].aggregateRating.reviewCount": "number",
  "data.items[].starRating": "number",
  "data.items[].mealPlan": "string",
  "data.items[].freeCancellation": "boolean",
  "data.items[].noPrepayment": "boolean",
  "data.items[].soldOut": "boolean",
  "data.items[].preferred": "boolean",
  "data.items[].preferredPlus": "boolean",
  "data.items[].highlighted": "boolean",
  "data.items[].sponsored": "boolean",
  "data.items[].sustainable": "boolean",
  "data.items[].badges[]": "string",
  "data.items[].cardLabels[]": "string",
  "data.items[].certifications[]": "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": "77777777-1111-4111-8111-777777777777",
  "executionId": "77777777-2222-4222-8222-777777777777",
  "data": {
    "source": "booking.com.br",
    "type": "plp",
    "url": "https://www.booking.com/searchresults.pt-br.html?ss=curitiba+parana&checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL",
    "requestUrl": "https://www.booking.com/searchresults.pt-br.html?ss=curitiba+parana&checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL",
    "extractedAt": "2026-02-12T12:34:56.000Z",
    "keyword": "curitiba parana",
    "query": "curitiba parana",
    "checkinDate": "2026-11-26",
    "checkoutDate": "2026-11-27",
    "numAdults": 2,
    "numChildren": 0,
    "numRooms": 1,
    "lang": "pt-br",
    "currency": "BRL",
    "destination": {
      "name": "Curitiba",
      "countryCode": "br",
      "destId": -664257,
      "destType": "city"
    },
    "totalResults": 438,
    "primaryResults": 438,
    "page": 2,
    "resultsPerPage": 25,
    "offset": 25,
    "nextPage": 3,
    "nextPageUrl": "https://www.booking.com/searchresults.pt-br.html?ss=curitiba+parana&checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL&offset=50",
    "items": [
      {
        "url": "https://www.booking.com/hotel/br/pavilhao-egipcio.pt-br.html",
        "propertyId": 10614217,
        "pageName": "br/pavilhao-egipcio.pt-br.html",
        "name": "Pavilhao Egipcio",
        "address": "Rua Lamenha Lins, 3152",
        "city": "Curitiba",
        "countryCode": "br",
        "latitude": -25.445358,
        "longitude": -49.266693,
        "distance": "1.9 km do centro",
        "distanceMeters": 1900,
        "thumbnail": "https://cf.bstatic.com/xdata/images/hotel/square240/729526152.jpg",
        "currency": "BRL",
        "price": 220,
        "regularPrice": 247.9,
        "averagePricePerNight": 220,
        "aggregateRating": {
          "rating": 9.2,
          "reviewCount": 146
        },
        "starRating": 4,
        "mealPlan": "Cafe da manha disponivel",
        "freeCancellation": true,
        "noPrepayment": false,
        "soldOut": false,
        "preferred": true,
        "preferredPlus": false,
        "highlighted": true,
        "sponsored": false,
        "sustainable": true,
        "badges": [
          "Muito bem avaliado"
        ],
        "cardLabels": [
          "Genius"
        ],
        "certifications": [
          "Travel Sustainable"
        ]
      }
    ]
  }
}

Complete field reference

PathTypeDescriptionExample
data.checkinDate string (YYYY-MM-DD) Field data.checkinDate returned in the response payload. 2026-11-26
data.checkoutDate string (YYYY-MM-DD) Field data.checkoutDate returned in the response payload. 2026-11-27
data.currency string Field data.currency returned in the response payload. BRL
data.destination.countryCode string data.destination.countryCode field returned in the response payload. br
data.destination.destId number Field data.destination.destId returned in the response payload. -664257
data.destination.destType string Field data.destination.destType returned in the response payload. city
data.destination.name string Field data.destination.name returned in the response payload. Curitiba
data.extractedAt string (iso datetime) data.extractedAt field returned in the response payload. 2026-02-12T12:34:56.000Z
data.items[].address string Field data.items[].address returned in the response payload. Rua Lamenha Lins, 3152
data.items[].aggregateRating.rating number Field data.items[].aggregateRating.rating returned in the response payload. 9.2
data.items[].aggregateRating.reviewCount number Field data.items[].aggregateRating.reviewCount returned in the response payload. 146
data.items[].averagePricePerNight number Field data.items[].averagePricePerNight returned in the response payload. 220
data.items[].badges[] string Field data.items[].badges[] returned in the response payload. Muito bem avaliado
data.items[].cardLabels[] string Field data.items[].cardLabels[] returned in the response payload. Genius
data.items[].certifications[] string Field data.items[].certifications[] returned in the response payload. Travel Sustainable
data.items[].city string Field data.items[].city returned in the response payload. Curitiba
data.items[].countryCode string Field data.items[].countryCode returned in the response payload. br
data.items[].currency string data.items[].currency field returned in the response payload. BRL
data.items[].distance string Field data.items[].distance returned in the response payload. 1.9 km do centro
data.items[].distanceMeters number Field data.items[].distanceMeters returned in the response payload. 1900
data.items[].freeCancellation boolean Field data.items[].freeCancellation returned in the response payload. true
data.items[].highlighted boolean Field data.items[].highlighted returned in the response payload. true
data.items[].latitude number Field data.items[].latitude returned in the response payload. -25.445358
data.items[].longitude number Field data.items[].longitude returned in the response payload. -49.266693
data.items[].mealPlan string Field data.items[].mealPlan returned in the response payload. Cafe da manha disponivel
data.items[].name string data.items[].name field returned in the response payload. Pavilhao Egipcio
data.items[].noPrepayment boolean data.items[].noPrepayment field returned in the response payload. false
data.items[].pageName string Field data.items[].pageName returned in the response payload. br/pavilhao-egipcio.pt-br.html
data.items[].preferred boolean Field data.items[].preferred returned in the response payload. true
data.items[].preferredPlus boolean Field data.items[].preferredPlus returned in the response payload. false
data.items[].price number Field data.items[].price returned in the response payload. 220
data.items[].propertyId number Field data.items[].propertyId returned in the response payload. 10614217
data.items[].regularPrice number Field data.items[].regularPrice returned in the response payload. 247.9
data.items[].soldOut boolean Field data.items[].soldOut returned in the response payload. false
data.items[].sponsored boolean Field data.items[].sponsored returned in the response payload. false
data.items[].starRating number data.items[].starRating field returned in the response payload. 4
data.items[].sustainable boolean Field data.items[].sustainable returned in the response payload. true
data.items[].thumbnail string Field data.items[].thumbnail returned in the response payload. https://cf.bstatic.com/xdata/images/hotel/square240/729526152.jpg
data.items[].url string data.items[].url field returned in the response payload. https://www.booking.com/hotel/br/pavilhao-egipcio.pt-br.html
data.keyword string Field data.keyword returned in the response payload. curitiba parana
data.lang string Field data.lang returned in the response payload. pt-br
data.nextPage number Field data.nextPage returned in the response payload. 3
data.nextPageUrl string Field data.nextPageUrl returned in the response payload. https://www.booking.com/searchresults.pt-br.html?ss=curitiba+parana&checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL&offset=50
data.numAdults number data.numAdults field returned in the response payload. 2
data.numChildren number Field data.numChildren returned in the response payload. 0
data.numRooms number Field data.numRooms returned in the response payload. 1
data.offset number Field data.offset returned in the response payload. 25
data.page number Field data.page returned in the response payload. 2
data.primaryResults number Field data.primaryResults returned in the response payload. 438
data.query string data.query field returned in the response payload. curitiba parana
data.requestUrl string Same value as `data.url`; never exposes the queried internal endpoint. https://www.booking.com/searchresults.pt-br.html?ss=curitiba+parana&checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL
data.resultsPerPage number Field data.resultsPerPage returned in the response payload. 25
data.source string Field data.source returned in the response payload. booking.com.br
data.totalResults number Field data.totalResults returned in the response payload. 438
data.type string Field data.type returned in the response payload. plp
data.url string Field data.url returned in the response payload. https://www.booking.com/searchresults.pt-br.html?ss=curitiba+parana&checkin=2026-11-26&checkout=2026-11-27&group_adults=2&group_children=0&no_rooms=1&lang=pt-br&selected_currency=BRL
executionId string (uuid) Field executionId returned in the response payload. 77777777-2222-4222-8222-777777777777
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. 77777777-1111-4111-8111-777777777777

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 statusError codeMeaning
400INVALID_PAYLOADInvalid JSON or a request that violates the documented validation rules.
401UNAUTHORIZEDMissing authorization or an invalid API key or token.
402INSUFFICIENT_CREDITSThe account has insufficient credits for this operation.
403FORBIDDENThe account does not have access, or the API is temporarily disabled.
409EXECUTION_CONFLICTThe execution identifier conflicts with an incompatible execution state.
429RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTSA rate limit or simultaneous request limit was exceeded.
5xxUPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERRORAn upstream, worker or gateway failure. Failed requests follow the platform refund policy.

Other Booking operations