{
  "openapi": "3.0.1",
  "info": {
    "title": "HRS Reviews Scraper - Hotel Reviews, Guest Reviews, Ratings",
    "description": "HRS (hrs.com) hotel reviews by URL or hotel id. One row per review: 0-10 rating, 12 category scores, positives, negatives, hotel replies, traveller type, stay dates, language, text. Free hotel row: stars, address. Free filters: complaints only, business travel, German. Hotelbewertungen, Bewertungen.",
    "version": "1.0",
    "x-build-id": "20BPa3Qo85Oa4J3qT"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/kestrel~hrs-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-kestrel-hrs-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~hrs-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-kestrel-hrs-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~hrs-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-kestrel-hrs-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": "HRS hotel URLs",
            "type": "array",
            "description": "HRS hotel pages, e.g. [\"https://www.hrs.com/en/hotel/10520\"]: any language prefix (/de/, /fr/) works and the number after /hotel/ is the hotel id. Use for \"reviews of this HRS hotel\". A URL and its id are one hotel, harvested once. A URL from another site ends the run with the reason on the run card and nothing charged. One of startUrls or hotelIds is required.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "hotelIds": {
            "title": "HRS hotel ids",
            "type": "array",
            "description": "HRS numeric hotel ids, e.g. [\"10520\", \"162\"]: the number after /hotel/ in any hrs.com hotel URL. Up to 20 ids go into one request, so a portfolio of 200 hotels is ten calls: use for bulk or scheduled runs over a known list. An id HRS does not know costs nothing and is reported as a status row with status \"not_found\". One of startUrls or hotelIds is required.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "maxReviewsPerHotel": {
            "title": "Max reviews per hotel",
            "minimum": 0,
            "maximum": 20000,
            "type": "integer",
            "description": "Reviews delivered per hotel after sorting and filtering, e.g. 50 (default 200). 0 = every commented rating the hotel has: HRS returns the whole list in one call, typically 50-150 for a busy hotel, a few hundred at most. The cost control: at most N x $0.004 per hotel. Use with reviewsSort for \"the 30 newest reviews\" (most_recent) or \"the 20 worst\" (lowest_rated).",
            "default": 200
          },
          "reviewsSort": {
            "title": "Sort",
            "enum": [
              "most_recent",
              "oldest",
              "highest_rated",
              "lowest_rated"
            ],
            "type": "string",
            "description": "Order of the reviews before maxReviewsPerHotel cuts: \"most_recent\" (default), \"oldest\", \"highest_rated\" or \"lowest_rated\". \"lowest_rated\" with a small cap is a complaints feed; \"most_recent\" suits a daily schedule; \"oldest\" with cap 0 is the full history.",
            "default": "most_recent"
          },
          "maxRating": {
            "title": "Max rating (complaints)",
            "minimum": 0,
            "maximum": 10,
            "type": "number",
            "description": "0 (default) = keep every review. 1-10 = keep only reviews scored at or below it on HRS's 0-10 scale, e.g. 7 (7 is a middling stay, below 6 a bad one). Runs before billing: a hotel with 85 commented ratings of which 9 are at or below 7 delivers and bills 9 rows; the 76 others are counted as filtered in the status row. Use for \"negative reviews\", \"complaints\", \"what guests disliked\".",
            "default": 0
          },
          "travellerTypes": {
            "title": "Traveller types",
            "type": "array",
            "description": "Empty (default) = every guest. Otherwise keep only these HRS traveller types, e.g. [\"BUSINESS\"]: BUSINESS, PRIVATE, YOUNG_COUPLE, MATURE_COUPLE, FAMILY_SMALL_CHILDREN, FAMILY_OLDER_CHILDREN, GROUP, CONFERENCE. Use for \"what business travellers say\" or \"family reviews\". A single type is asked of HRS directly; several are filtered here. Filtered reviews are never billed.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "languages": {
            "title": "Languages",
            "type": "array",
            "description": "Empty (default) = every language. Otherwise keep only comments written in these languages, e.g. [\"de\"] or [\"de\", \"en\"]: codes de, en, fr, it, es, nl, pl, pt, ru, zh, tr, cs (or deu, eng, ...) or names (\"German\"). Most HRS comments are German, then English; nothing is translated. Use for \"German reviews only\". Filtered reviews are never billed.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "requireText": {
            "title": "Only reviews with a comment",
            "type": "boolean",
            "description": "false (default) = every commented rating. true = only rows with a written positive or negative. HRS's list already holds only commented ratings, so this rarely removes anything; set it when every billed row must carry text. Filtered rows are never billed.",
            "default": false
          },
          "includeHotelRow": {
            "title": "Hotel context rows",
            "type": "boolean",
            "description": "true (DEFAULT) = one free row per hotel (type \"hotel\") with name, stars, address, city, overall rating, rating count, recommendation rate and the averages by traveller type and by category, and the hotel name on every review row; costs one page read per hotel, no charge. false = no hotel rows and hotel_name empty on review rows: the cheapest daily poll over a known list of ids.",
            "default": true
          },
          "language": {
            "title": "Site language for hotel pages",
            "enum": [
              "en",
              "de",
              "fr",
              "it",
              "es",
              "nl",
              "pl",
              "pt",
              "ru",
              "zh_cn",
              "tr",
              "cs"
            ],
            "type": "string",
            "description": "Language of the hrs.com page read for the hotel row (name, address, stars): \"en\" (default), \"de\", \"fr\", \"it\", \"es\", \"nl\", \"pl\", \"pt\", \"ru\", \"zh_cn\", \"tr\", \"cs\". Review comments keep the language their author wrote in whatever you pass here; to keep only German comments use languages.",
            "default": "en"
          },
          "sessions": {
            "title": "Proxy sessions",
            "minimum": 1,
            "maximum": 16,
            "type": "integer",
            "description": "Proxy sessions (egress IPs) run in parallel, 1-16, e.g. 4 (default 4). More is faster; each session is paced separately.",
            "default": 4
          },
          "perIp": {
            "title": "Requests per second per session",
            "minimum": 0.1,
            "maximum": 3,
            "type": "number",
            "description": "Requests per second per session, 0.1-3, e.g. 1 (default 1). HRS answered 10 of 10 at 1/s on one residential IP.",
            "default": 1
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Apify Proxy RESIDENTIAL is required and is the default: hrs.com and its ratings API answer 403 to datacenter IPs. Traffic is small: one JSON call per 20 hotels plus one page per hotel for the hotel row.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}