{ "openapi": "3.0.1", "info": { "title": "HRS Hotel Reviews Scraper - Ratings, Replies & Scores", "description": "Scrape HRS hotel reviews with guest text, 12 category scores, stay dates, traveller type and the hotel's own reply. Search a city or paste hotel URLs. No key needed.", "version": "1.0", "x-build-id": "qyksnAHA9mgNrBMVF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~hrs-hotel-reviews-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-hrs-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/sian.agency~hrs-hotel-reviews-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-hrs-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/sian.agency~hrs-hotel-reviews-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-hrs-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": { "operation": { "title": "🎯 What to scrape", "enum": [ "reviews", "search", "hotelProfile" ], "type": "string", "description": "⭐ **HOTEL REVIEWS** β€” one row per guest review for the hotels you list: score, what the guest liked and disliked, twelve category scores, and the hotel's reply.\n\nπŸ”Ž **HOTEL SEARCH BY CITY** β€” a city's hotels with their aggregate rating. Use it to find hotel ids you do not have.\n\n🏨 **HOTEL PROFILES** β€” the full property record: address, chain, contact details, amenities, and the rating split by traveller type.\n\nπŸ’‘ **TIP:** search a city first, then run reviews on the ids it returns.", "default": "reviews" }, "hotels": { "title": "🏨 Hotels", "uniqueItems": true, "type": "array", "description": "🏨 **USED BY:** hotel reviews and hotel profiles. One hotel per line, in any of these forms:\n- An HRS hotel URL: `https://www.hrs.com/en/hotel/519245` (any language)\n- A bare hotel id: `519245`\n- The hotel's name: `Radisson Blu Hotel Bremen`\n\n⚠️ A `/hotel//d-` link is a city page, not a hotel. It is rejected with a note β€” put it in **Cities and areas** and use the search operation.", "default": [ "https://www.hrs.com/en/hotel/519245" ], "items": { "type": "string" } }, "maxReviewsPerHotel": { "title": "πŸ”’ Max reviews per hotel", "minimum": 1, "maximum": 5000, "type": "integer", "description": "πŸ”’ Stop after this many reviews for each hotel. HRS returns a hotel's whole published review history in one response, so this is a billing cap rather than a paging control.\n\nπŸ’‘ **TIP:** the deepest property we measured carried 155 written reviews, so the default of 200 takes everything for almost every hotel. Newest reviews come first, so a lower number gives you the latest.", "default": 200 }, "travellerType": { "title": "🧳 Traveller type", "enum": [ "ALLHRS", "BUSINESS", "PRIVATE", "YOUNG_COUPLE", "MATURE_COUPLE", "FAMILY_SMALL_CHILDREN", "FAMILY_OLDER_CHILDREN", "GROUP", "CONFERENCE" ], "type": "string", "description": "🧳 Filter reviews to one kind of guest, using HRS's own segmentation rather than a keyword guess. Business is the largest segment on most German properties.\n\n⚠️ Picking a segment narrows the result set considerably β€” a Munich hotel with 117 reviews returns 49 for Business and 14 for Mature couple. Leave it on **All travellers** unless you specifically want the split.", "default": "ALLHRS" }, "reviewsFrom": { "title": "πŸ“… Only reviews since", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "πŸ“… Keep only reviews written on or after this date, as `YYYY-MM-DD`. Leave it empty for the full history.\n\nπŸ’‘ **TIP:** on a schedule, set it to your last run's date and you pay only for what is new. Dates are HRS's own review timestamps, recorded in Europe/Berlin time.", "default": "" }, "onlyWithText": { "title": "✍️ Only reviews with written text", "type": "boolean", "description": "✍️ Drop reviews that carry scores but no written comment.\n\nℹ️ Every review HRS publishes on the web already has text β€” the score-only ratings sit behind the aggregate and are not returned β€” so this changes almost nothing in practice. It is here for pipelines that want the guarantee in writing.", "default": false }, "includeHotelReplies": { "title": "πŸ’¬ Include hotel replies", "type": "boolean", "description": "πŸ’¬ Keep the hotel's own answer to each review.\n\nπŸ“Š Roughly 39% of reviews carry a reply to the positive half and 28% to the negative half, so reply rate is itself a useful signal. Switch this off for a leaner dataset when you only want guest voice.", "default": true }, "places": { "title": "πŸ“ Cities and areas", "uniqueItems": true, "type": "array", "description": "πŸ“ **USED BY:** hotel search.\n\nOne place per line:\n- A city or region name in any language: `Munich`, `MΓΌnchen`, `Wien`, `ZΓΌrich`\n- An HRS destination URL: `https://www.hrs.com/en/destination/70801`\n\nπŸ”Ž Names are resolved through HRS's own location lookup, so the place you get is the place the website would give you.", "default": [ "Munich" ], "items": { "type": "string" } }, "maxHotelsPerPlace": { "title": "πŸ”’ Max hotels per city", "minimum": 1, "maximum": 1000, "type": "integer", "description": "πŸ”’ How many hotels to take from each city search.\n\nℹ️ HRS caps its own result set at 1000 hotels per city, so that is the ceiling here too. Hotels come back in HRS's own recommendation order, so a lower number gives you the ones the site itself puts first.", "default": 100 } } }, "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 } } } } } } } } } }