{
  "openapi": "3.0.1",
  "info": {
    "title": "Booking.com Reviews Scraper",
    "description": "Extract Booking.com guest reviews at scale — 24 structured fields per review (positive/negative text, score, traveler type, room, reviewer profile, owner response). Feed hotel URLs or a destination name, get ready-to-analyze JSON. MCP-ready for Claude, Cursor, ChatGPT, and AI agents.",
    "version": "1.2",
    "x-build-id": "3EfYdq1jWtkwYMuOK"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~booking-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-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/khadinakbar~booking-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-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/khadinakbar~booking-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-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": "Hotel URLs",
            "type": "array",
            "description": "Use this field when the user provides direct Booking.com hotel/property page URLs (e.g. https://www.booking.com/hotel/us/the-plaza.html). Each item must be a booking.com /hotel/ URL. Do NOT use this when the user wants to search by destination — use searchQuery for that instead.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "searchQuery": {
            "title": "Search Query (destination)",
            "type": "string",
            "description": "Use this field when the user provides a city, region, neighborhood, or destination name (e.g. 'Paris', 'New York Manhattan', 'Bali beachfront'). The actor will search Booking.com for hotels matching this query and scrape their reviews. Do NOT use this when specific hotel URLs are provided — use startUrls for that."
          },
          "checkIn": {
            "title": "Check-in Date (for search only)",
            "type": "string",
            "description": "Check-in date in YYYY-MM-DD format. Only used together with searchQuery to filter hotels by availability. Leave empty to search without date filter."
          },
          "checkOut": {
            "title": "Check-out Date (for search only)",
            "type": "string",
            "description": "Check-out date in YYYY-MM-DD format. Only used together with searchQuery. Must be after checkIn."
          },
          "maxReviewsPerHotel": {
            "title": "Max Reviews Per Hotel",
            "minimum": 1,
            "maximum": 99999,
            "type": "integer",
            "description": "Maximum number of reviews to scrape per hotel/property. Set to a high number (e.g. 9999) to scrape all available reviews. Higher values take proportionally longer and cost more.",
            "default": 100
          },
          "maxHotelsFromSearch": {
            "title": "Max Hotels From Search",
            "minimum": 1,
            "maximum": 30,
            "type": "integer",
            "description": "Only used when searchQuery is provided. Caps how many hotels the destination search scrapes. Default is 5 — keeps typical run times under 5 minutes. Raise to 30 for exhaustive destination sweeps (will take proportionally longer). Ignored when only startUrls is provided.",
            "default": 5
          },
          "sortReviewsBy": {
            "title": "Sort Reviews By",
            "enum": [
              "f_relevance",
              "f_recent_desc",
              "f_recent_asc",
              "f_score_desc",
              "f_score_asc"
            ],
            "type": "string",
            "description": "Order in which reviews are retrieved from Booking.com. 'Most Relevant' is the default. Use 'Newest First' combined with cutoffDate to efficiently get only recent reviews without scraping the entire review history.",
            "default": "f_relevance"
          },
          "filterByScore": {
            "title": "Filter By Score",
            "enum": [
              "f_all_reviews",
              "review_adj_superb",
              "review_adj_good",
              "review_adj_average_passable",
              "review_adj_poor"
            ],
            "type": "string",
            "description": "Only retrieve reviews matching a specific score category. Use 'All scores' to include reviews of any rating. Useful when you only want to analyze negative feedback ('Poor') or excellent experiences ('Superb').",
            "default": "f_all_reviews"
          },
          "filterByTravelerType": {
            "title": "Filter By Traveler Type",
            "enum": [
              "",
              "couple",
              "solo_traveller",
              "family_with_children",
              "group_of_friends",
              "business_traveler"
            ],
            "type": "string",
            "description": "Only scrape reviews from guests of a specific traveler type. Leave blank to get reviews from all traveler types. Useful for targeted analysis (e.g. business traveler feedback vs family feedback).",
            "default": ""
          },
          "filterByLanguage": {
            "title": "Filter By Review Language",
            "type": "string",
            "description": "Only retrieve reviews written in this language. Leave empty to scrape reviews in all languages. Use ISO 639-1 two-letter codes: en (English), de (German), fr (French), es (Spanish), it (Italian), nl (Dutch), pt (Portuguese), ru (Russian), zh (Chinese), ja (Japanese), ko (Korean), ar (Arabic), etc.",
            "default": ""
          },
          "cutoffDate": {
            "title": "Cutoff Date (stop before this date)",
            "type": "string",
            "description": "Stop scraping reviews that are older than this date (format: YYYY-MM-DD). Works most efficiently when combined with Sort='Newest First' — the actor stops as soon as it encounters a review older than this date, saving time and cost. Leave empty to scrape all reviews up to maxReviewsPerHotel."
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Proxy settings for bypassing Cloudflare protection. Apify datacenter proxies are recommended as the default. Switch to residential proxies if you encounter persistent blocking (lower success rate).",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}