{
  "openapi": "3.0.1",
  "info": {
    "title": "Booking.com Reviews Scraper — Hotel Guest Reviews & Ratings",
    "description": "Every guest review of any Booking.com hotel: 1-10 score, title, what guests liked and disliked, language, stay dates, room, traveller type, reviewer country, photos and the property's reply. Give Booking.com URLs, hotel names or ids. No browser, no login. Pay per review.",
    "version": "1.0",
    "x-build-id": "lddnq38mQ32CeBa2q"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/kestrel~booking-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-kestrel-booking-reviews-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/kestrel~booking-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-kestrel-booking-reviews-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/kestrel~booking-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-kestrel-booking-reviews-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "startUrls": {
            "title": "Booking.com hotel URLs",
            "uniqueItems": true,
            "type": "array",
            "description": "Booking.com property pages, e.g. https://www.booking.com/hotel/pt/memmo-alfama.html — any language variant (.en-gb.html, .de.html) and query string is fine. The property is resolved through Booking's own autocomplete, and the resolved name comes back in the hotel and status rows so you can check the match.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "hotelNames": {
            "title": "Hotel names",
            "uniqueItems": true,
            "type": "array",
            "description": "Property names as you would type them into Booking's search box, e.g. \"Memmo Alfama Lisbon\" — add the city to disambiguate chains. The first hotel Booking's autocomplete returns is used; its full name comes back in the rows.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "hotelIds": {
            "title": "Booking.com hotel ids",
            "uniqueItems": true,
            "type": "array",
            "description": "Booking's numeric property ids, e.g. 536251 — what an earlier run's hotel_id gives you. The fastest path: no lookup at all. Ids carry no name, so give a URL or a name if you want hotel_name filled.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "maxReviewsPerHotel": {
            "title": "Max reviews per hotel",
            "minimum": 0,
            "maximum": 20000,
            "type": "integer",
            "description": "0 = every review the property has (Booking pages them 25 at a time; big hotels run into the thousands). N = the first N in the order below. The main cost control.",
            "default": 200
          },
          "reviewsSort": {
            "title": "Order",
            "enum": [
              "most_recent",
              "highest_rated",
              "lowest_rated",
              "most_relevant",
              "oldest"
            ],
            "type": "string",
            "description": "Which reviews come first. \"Lowest rated\" is the fastest way to find complaints; \"Most recent\" is the one to schedule.",
            "default": "most_recent"
          },
          "languages": {
            "title": "Review languages",
            "uniqueItems": true,
            "type": "array",
            "description": "Leave empty for every language. Otherwise the language codes to keep — en, de, fr, es, it, pt, nl, ru, ja, zh, ko, tr … — as Booking's own language filter uses them. Booking filters server-side, so the reviews you skip are never fetched or charged. The hotel row lists how many reviews each language holds.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "travelerType": {
            "title": "Traveller type",
            "enum": [
              "all",
              "families",
              "couples",
              "friends",
              "solo",
              "business"
            ],
            "type": "string",
            "description": "Keep only reviews from one kind of guest, filtered by Booking itself (skipped reviews are never fetched or charged).",
            "default": "all"
          },
          "keyword": {
            "title": "Only reviews mentioning",
            "type": "string",
            "description": "A word or phrase Booking searches the reviews for (\"breakfast\", \"noise\", \"parking\"). Server-side, so only matching reviews are fetched and charged. Leave empty for all.",
            "default": ""
          },
          "maxRating": {
            "title": "Only reviews at or below this score",
            "minimum": 0,
            "maximum": 10,
            "type": "number",
            "description": "0 = keep every review. 1-10 on Booking's scale = keep only reviews at or below it. Reviews are then read lowest score first and paging stops at the threshold, so a complaints feed reads only the pages that carry complaints. Filtered reviews are never charged.",
            "default": 0
          },
          "requireText": {
            "title": "Only reviews with a written comment",
            "type": "boolean",
            "description": "Deliver and pay for only the reviews where the guest wrote something in \"liked\" or \"disliked\" — Booking allows title-only reviews, and this drops them before billing.",
            "default": false
          },
          "locale": {
            "title": "Site language",
            "type": "string",
            "description": "Booking locale for the request, e.g. en-US, en-GB, de-DE, fr-FR. It sets the language of Booking's labels (traveller type, country names); reviews always come back in the language they were written in.",
            "default": "en-US"
          },
          "includeHotelRow": {
            "title": "Include a hotel row",
            "type": "boolean",
            "description": "Also emit one row per property with its id, name and location, Booking's seven category scores (staff, facilities, cleanliness, comfort, value, location, Wi-Fi), the review count and how many reviews each language and traveller type holds. Never charged.",
            "default": true
          },
          "sessions": {
            "title": "Parallel sessions",
            "minimum": 1,
            "maximum": 16,
            "type": "integer",
            "description": "How many proxy sessions (egress IPs) run in parallel. More is faster; each is paced separately.",
            "default": 4
          },
          "perIp": {
            "title": "Requests per second per IP",
            "minimum": 0.1,
            "maximum": 3,
            "type": "number",
            "description": "Pace for each session. Booking answered 10 calls at 1/s from one IP without a hiccup in testing; 1/s per IP is the default.",
            "default": 1
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Apify Proxy is required so runs rotate IPs. The default datacenter group works for Booking's review endpoint (only Booking's HTML pages need a browser, and this actor never loads one).",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}