{ "openapi": "3.0.1", "info": { "title": "HRS Reviews Scraper — Hotel Guest Reviews & Ratings", "description": "Every commented guest review of any HRS (hrs.com) hotel: 0-10 rating with twelve category votes, what guests liked and disliked, the hotel's replies, traveller type, stay dates and language, plus each property's averages by traveller type. Give HRS URLs or hotel ids. Pay per review.", "version": "1.0", "x-build-id": "zUErB0OtciuDQugyh" }, "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 works; the number is the hotel id.", "default": [], "items": { "type": "string" } }, "hotelIds": { "title": "HRS hotel ids", "type": "array", "description": "HRS numeric hotel ids, e.g. 10520 — the number after /hotel/ in any hrs.com hotel URL. Faster than URLs for long lists; up to 20 ids go into one request.", "default": [], "items": { "type": "string" } }, "maxReviewsPerHotel": { "title": "Max reviews per hotel", "minimum": 0, "maximum": 20000, "type": "integer", "description": "0 = every commented rating the hotel has (HRS returns the whole list in one call; a busy hotel has a few hundred). N = only the first N in the chosen order — the cost control.", "default": 200 }, "reviewsSort": { "title": "Sort", "enum": [ "most_recent", "oldest", "highest_rated", "lowest_rated" ], "type": "string", "description": "Which reviews come first before the cap applies. \"Lowest rated\" is the fastest way to a complaints feed; \"Most recent\" suits a schedule.", "default": "most_recent" }, "travellerTypes": { "title": "Traveller types", "type": "array", "description": "Leave empty for every guest. Otherwise keep only these HRS traveller types: BUSINESS, PRIVATE, YOUNG_COUPLE, MATURE_COUPLE, FAMILY_SMALL_CHILDREN, FAMILY_OLDER_CHILDREN, GROUP, CONFERENCE. Filtered reviews are never billed.", "default": [], "items": { "type": "string" } }, "languages": { "title": "Languages", "type": "array", "description": "Leave empty for every language. Otherwise keep only comments written in these languages, as codes (de, en, fr, it, es, nl, pl, pt, ru, zh, tr, cs — or the 3-letter deu, eng, …) or names (German, English…). Filtered reviews are never billed.", "default": [], "items": { "type": "string" } }, "maxRating": { "title": "Max rating (complaints)", "minimum": 0, "maximum": 10, "type": "number", "description": "0 = keep every review. 1-10 on the HRS scale (7 is a middling stay, below 6 is a bad one) = keep only reviews at or below it. Runs before billing, so a complaints feed pays for the complaints only.", "default": 0 }, "requireText": { "title": "Only reviews with a comment", "type": "boolean", "description": "HRS's list already contains only ratings with a written positive or negative, so this rarely removes anything; it guarantees every billed row carries text.", "default": false }, "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). Review comments keep the language their author wrote in.", "default": "en" }, "includeHotelRow": { "title": "Hotel context rows", "type": "boolean", "description": "Also emit one free row per hotel with name, stars, address, overall rating, rating count, recommendation rate, and the averages by traveller type and by category — and put the hotel name on every review row. Off = one request fewer per hotel, but no names.", "default": true }, "sessions": { "title": "Proxy 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 session", "minimum": 0.1, "maximum": 3, "type": "number", "description": "Pace for each session. HRS answered 10 of 10 at 1/s on one residential IP in testing.", "default": 1 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify Proxy RESIDENTIAL is required: both hrs.com and its ratings API answer 403 to datacenter IPs (Akamai and CloudFront). Residential 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 } } }, "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 } } } } } } } } } }