{
  "openapi": "3.0.1",
  "info": {
    "title": "Booking.com Review Scraper",
    "description": "Which room type gets the complaints? What do guests really say about your breakfast? Scrape Booking.com reviews at room level — score, liked/disliked texts, stay details, traveler type, management replies — with score-band filters and topic search. Deduplicated, LLM-ready.",
    "version": "0.0",
    "x-build-id": "dOnJIUf2VSPoGwiDH"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/noraview~booking-com-review-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-noraview-booking-com-review-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/noraview~booking-com-review-scraper/runs": {
      "post": {
        "operationId": "runs-sync-noraview-booking-com-review-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/noraview~booking-com-review-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-noraview-booking-com-review-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",
        "required": [
          "hotelUrls"
        ],
        "properties": {
          "hotelUrls": {
            "title": "🏨 Hotel URLs",
            "type": "array",
            "description": "Booking.com hotel URLs to scrape reviews for.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "maxReviewsPerHotel": {
            "title": "📊 Max Reviews per Hotel",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Newest reviews to collect per hotel (sorted newest first). ~200 = 8 pages.",
            "default": 200
          },
          "cutoffMonths": {
            "title": "📅 Cutoff (months)",
            "minimum": 1,
            "maximum": 120,
            "type": "integer",
            "description": "Stop paginating once reviews are older than this many months — beyond that a review no longer describes the hotel as it is today.",
            "default": 24
          },
          "sort": {
            "title": "Sort Order",
            "enum": [
              "f_recent_desc",
              "f_recent_asc",
              "f_score_desc",
              "f_score_asc",
              "f_relevance"
            ],
            "type": "string",
            "description": "Booking.com review sort order.",
            "default": "f_recent_desc"
          },
          "reviewScoreFilter": {
            "title": "Review scores filter",
            "type": "array",
            "description": "Filter reviews by score band (server-side, same as Booking's own filter — no wasted pages). 'All' = no filter. Multiple bands = one pass per band, merged and deduplicated.",
            "items": {
              "type": "string",
              "enum": [
                "all",
                "superb",
                "good",
                "passable",
                "poor",
                "very_poor"
              ],
              "enumTitles": [
                "All",
                "Superb: 9+",
                "Good: 7-9",
                "Passable: 5-7",
                "Poor: 3-5",
                "Very poor: 1-3"
              ]
            },
            "default": [
              "all"
            ]
          },
          "searchText": {
            "title": "🔍 Search in reviews (optional)",
            "type": "string",
            "description": "Same as Booking's 'Search guest reviews by topic' bar — server-side semantic search (e.g. 'breakfast', 'pool', 'noise', 'wifi'). Leave empty for no search. Combines with the score filter.",
            "default": ""
          },
          "minTextChars": {
            "title": "✍️ Min text length (chars)",
            "minimum": 1,
            "type": "integer",
            "description": "A review counts as 'written' when its liked + disliked text (not the title) has at least this many characters, ignoring placeholder answers (nothing, none, n/a, na, -, ., no, nothing to dislike, all good, everything, rien, aucun, nada, ninguno, nichts). Each Japanese, Korean or Chinese character counts as 3, so 25 means about 9 CJK characters. When set, `has_text` on each review means 'written' instead of 'has any text'."
          },
          "targetWrittenReviews": {
            "title": "🎯 Target written reviews",
            "minimum": 1,
            "type": "integer",
            "description": "Keep fetching pages (newest first) until this many written reviews dated within 'Recent window' are collected. Requires 'Min text length'. Stops earlier at the max age or max reviews limit. Whole pages are kept, so the final count can exceed the target by up to 24."
          },
          "recentMonths": {
            "title": "Recent window (months)",
            "minimum": 1,
            "maximum": 120,
            "type": "integer",
            "description": "Window used to count written reviews toward the target (and for `written_recent` in the summary). Only used with 'Min text length'.",
            "default": 12
          },
          "maxAgeMonths": {
            "title": "📅 Max review age (months)",
            "minimum": 1,
            "maximum": 120,
            "type": "integer",
            "description": "Stop paginating once reviews are older than this. When set, replaces 'Cutoff (months)'."
          },
          "useApifyProxy": {
            "title": "Force Apify residential proxy",
            "type": "boolean",
            "description": "OFF by default — the scraper first tries cheap datacenter IPs. Turn ON only to force the residential proxy from the start (more expensive, rarely needed while auto fallback below is enabled).",
            "default": false
          },
          "autoProxyFallback": {
            "title": "🛡️ Auto fallback to residential proxy",
            "type": "boolean",
            "description": "Tries datacenter IPs first; if Booking blocks us (WAF / CAPTCHA / HTTP 403-429), the same hotel is automatically retried through Apify's residential proxy. Best cost/reliability balance.",
            "default": true
          },
          "proxyCountries": {
            "title": "Proxy Countries",
            "type": "array",
            "description": "Source markets to route the proxy through. Reviews are geo-independent — this is only for proxy-pool diversity, not per-country cohorts. One country is normal.",
            "default": [
              "FR"
            ],
            "items": {
              "type": "string"
            }
          },
          "proxyUrl": {
            "title": "External Proxy URL (optional)",
            "type": "string",
            "description": "Used only if 'Use Apify Proxy' is off. Format: http://user:pass@host:port",
            "default": ""
          },
          "delayBetweenRequests": {
            "title": "Delay Between Page Requests (seconds)",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Wait time between each review page fetch.",
            "default": 2
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}