{
  "openapi": "3.0.1",
  "info": {
    "title": "Hotel Reviews Scraper (Booking.com + Agoda)",
    "description": "Paste Booking.com or Agoda hotel URLs, or hotel names such as The Savoy London, and get guest reviews: score, liked and disliked text, reviewer country, traveler type, stay dates, hotel reply. A name can pull one hotel from both sites. Free summary row. $1.80 per 1,000 reviews, failures free.",
    "version": "1.0",
    "x-build-id": "g7bJ3QWb1D1ecYcf2"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/heyitsgautham~hotel-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-heyitsgautham-hotel-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/heyitsgautham~hotel-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-heyitsgautham-hotel-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/heyitsgautham~hotel-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-heyitsgautham-hotel-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": {
          "hotelUrls": {
            "title": "Hotel URLs",
            "type": "array",
            "description": "Booking.com or Agoda hotel page URLs, or leave empty and use Hotel names below. The site is detected from the URL. Booking.com: https://www.booking.com/hotel/gb/the-savoy.html (any language suffix or query string is fine). Agoda: https://www.agoda.com/the-peninsula-hong-kong/hotel/hong-kong-hk.html, or any Agoda link with a hotel_id or hid parameter.",
            "items": {
              "type": "string"
            }
          },
          "hotelNames": {
            "title": "Hotel names",
            "type": "array",
            "description": "Hotel names as you would type them into the site's search box, with the city, such as The Savoy London or Mandarin Oriental Bangkok. The actor searches the site below and scrapes the hotel the name matches, and every row says which hotel that was in matchedHotel. A name that matches no hotel, or several hotels equally well (Hilton London), gives a free row instead, and the tie row lists up to 5 candidates with their URLs. A URL is always the most precise input.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "nameSite": {
            "title": "Site to search names on",
            "enum": [
              "booking",
              "agoda",
              "both"
            ],
            "type": "string",
            "description": "Which site's reviews to get for the hotel names above. URLs pick their site themselves. Both looks each name up on Booking.com and Agoda and scrapes both only when the two listings are the same hotel by name, country and map position. A paired hotel's Agoda rows then hold only Agoda's own reviews, since the Booking.com reviews Agoda shows are already in the Booking.com rows. When only one site has a clear match, that site is scraped alone and the other gets a free row saying why. The review limit applies on each site.",
            "default": "booking"
          },
          "maxReviewsPerHotel": {
            "title": "Max reviews per hotel",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Stops after this many reviews for each hotel. You pay only for reviews returned.",
            "default": 100
          },
          "sortBy": {
            "title": "Sort reviews by",
            "enum": [
              "newest",
              "relevant",
              "highest",
              "lowest"
            ],
            "type": "string",
            "description": "Which reviews to take first. On Agoda, Most relevant uses Agoda's Most helpful order.",
            "default": "newest"
          },
          "languages": {
            "title": "Review languages",
            "type": "array",
            "description": "Only return reviews written in these languages, as ISO 639-1 codes such as en, de, fr, ja, zh. Leave empty for all languages.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "hotelSummary": {
            "title": "Free summary row per hotel",
            "type": "boolean",
            "description": "Adds one free row with status summary per hotel, after its reviews. It gives the reviews this run returned (count, average score, score bands, date range, low-score share, hotel reply share, traveler types, reviewer countries, languages and review sources) and each site's own rating, review count and sub-ratings for the whole hotel, with Agoda's score bands. With both sites it splits the figures per site. It is never charged and needs no extra request.",
            "default": false
          },
          "onlyNewSinceLastRun": {
            "title": "Only new since the last run",
            "type": "boolean",
            "description": "For scheduled runs. Returns only reviews this actor has not returned to you before for the same hotel and filters, and nothing older than the newest one it returned last time. The first run returns the usual results and remembers them. Works best with newest-first order, where the run stops at the first page with nothing new. The memory is a key-value store named hotel-reviews-scraper-monitor in your Apify account.",
            "default": false
          },
          "publishedAfter": {
            "title": "Published after",
            "pattern": "^$|^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$|^\\d+\\s*(minute|hour|day|week|month|year)s?(\\s+ago)?$",
            "type": "string",
            "description": "Only reviews published on or after this date. Use a date such as 2026-10-01, an ISO time such as 2026-10-01T12:00:00Z (UTC), or a relative value such as 7 days, meaning the last 7 days. With newest-first order the run stops as soon as it reaches older ones."
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many hotels to scrape in parallel.",
            "default": 5
          },
          "useProxy": {
            "title": "Use residential proxy",
            "type": "boolean",
            "description": "Leave on. Both sites block or empty out answers to cloud IPs.",
            "default": 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
                  },
                  "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}