HolidayCheck Hotel Reviews API - Guest Feedback and Ratings
Get paginated guest reviews and the hotel's native six-point rating summary.
Overview
Read HolidayCheck hotel reviews with StayAPI: six-point ratings, text sections, recommendation percentage, review timestamps, stay months, and paginated feedback.
Scope
A hotel UUID works directly; URL resolution is optional. Each page returns up to 10 reviews. There is no per_page or language control. Text is returned as supplied by HolidayCheck; language and original_language report source metadata. There is no requested translation or language filter. Ratings remain on HolidayCheck's six-point scale, while recommendation_percent is a percentage. Owner responses are not included.
Authentication
Send your StayAPI key in the X-API-Key header. Each successful call costs one credit. Successful requests return JSON; failures use RFC 7807 Problem Details.
Endpoint URL
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| hotel_id | string | Required | Hotel UUID from Hotel Name Search, a supported HolidayCheck URL, or URL to Hotel ID. |
| page | integer | Optional | Page number, at least 1. Default: 1. Fixed maximum of 10 reviews per page. |
| sort | enum | Optional | most_relevant (default) or recent_desc (newest first). |
Response schema
The response example is illustrative. Optional source values can be null. Review counts and ratings change over time.
| Field | Type | Description |
|---|---|---|
| hotel_id / hotel_name / url | string | Hotel UUID, published hotel name, and canonical HolidayCheck review-listing URL. |
| summary.rating / summary.rating_scale | number or null / integer | Published hotel rating, nullable when unavailable; rating_scale is always 6. |
| summary.recommendation_percent | number or null | Published recommendation percentage, not a six-point rating. |
| summary.total_reviews / total_count | integer | Total published reviews used for pagination. |
| reviews | array | Up to 10 reviews. A confirmed zero-review hotel or a page past the end returns an empty array with HTTP 200. |
| reviews[].id | string | Stable review identifier. |
| reviews[].title / text | string or null | Published review title and main text, when available. |
| reviews[].text_sections | array | Structured text sections, each with key, label, and text. Empty when no sections are supplied. |
| reviews[].rating / rating_scale | number or null / integer | Native review rating when supplied; rating_scale is always 6. |
| reviews[].review_date | string or null | ISO timestamp of the upstream review entry; not the stay date. |
| reviews[].stay_date | string or null | Stay month in YYYY-MM format; no invented day. |
| reviews[].original_language / language | string or null | original_language is the original locale; language is the returned locale. They may differ. No translation or language filter can be requested. |
| reviews[].reviewer_name / traveler_type | string or null | Published reviewer name and traveler category, when supplied. |
| reviews[].recommended / verified_stay | boolean or null | Published recommendation and verified-stay indicators. Null means unavailable, not false. |
| page / per_page / has_more | integer / integer / boolean | Requested page, fixed page size of 10, and whether another page exists. |
| retrieved_at | string | ISO timestamp for this response. |
Errors and limitations
Errors use RFC 7807 Problem Details with provider: "holidaycheck" and a correlation id.
- 422: missing or invalid hotel UUID, invalid page, or unsupported sort.
- 404: the hotel is confirmed missing.
- 500: the response could not be interpreted.
- 502: HolidayCheck data is unavailable or access was blocked.
- 503: temporarily rate-limited or unavailable; honor
Retry-Afterwhen supplied. - 504: the request timed out.
- 401 / 402 / 429: check your API key, available credits, and account rate limit.