GET
# Hotel Reviews API

Access detailed customer reviews, ratings, and feedback from various booking platforms including Booking.com.

## Overview

#### Rich Review Data

Get comprehensive review information including ratings, text reviews, reviewer details, and review metadata for in-depth analysis.

The Hotel Reviews endpoint provides access to customer reviews and ratings from major booking platforms. Perfect for sentiment analysis, hotel performance tracking, and providing social proof to your users.

### Endpoint URL

GET https://api.stayapi.com/v1/booking/hotel/reviews 

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| hotel\_id | string | Required | Booking.com hotel ID (numeric string, e.g., "1302021") |
| page | integer | Optional | Page number for pagination (default: 1) |
| per\_page | integer | Optional | Number of reviews per page (default: 10, max: 25) |
| language | string | Optional | Filter by language group (e.g., "en", "fr", "es"); regional variants share a group. Omit for all languages. |
| sort | string | Optional | Review ordering. One of `most_relevant` (default), `recent_desc`, `recent_asc`, `score_asc`, `score_desc`. Use `recent_desc` for newest-first order — ideal for date-range backfills. |
| include\_stay\_dates | boolean | Optional | Default false. Include available check-in and check-out dates. |

#### Date-range backfill (e.g. last 12 months)

Pass sort=recent\_desc, deduplicate by review id across pages, and stop as soon as a review's reviewed\_date falls past your cutoff. This typically fetches a small fraction of a property's total review history instead of every review ever submitted.

## Common Use Cases

### Sentiment Analysis

Analyze customer sentiment and satisfaction trends to understand hotel performance over time.

Perfect for business intelligence

### Social Proof

Display recent customer reviews to build trust and encourage bookings on your platform.

Increase conversion rates

### Competitive Analysis

Compare review trends and ratings across competing hotels in the same market.

Market intelligence

### Content Generation

Use review highlights and common themes to generate marketing content and descriptions.

Automated content creation

## Review identifiers and missing values

Review IDs are opaque strings. Store them as returned and deduplicate within a hotel; they do not match historical numeric IDs. Reviewer IDs, travel purpose, and selected room photos are no longer returned. Reviewer-uploaded photos remain available.

`is_incentivised` is null when unknown. `guest.nr_reviews` is null when unavailable; do not substitute zero. Relevance ordering can change and pages can overlap. Use `sort=recent_desc` for date backfills and deduplicate by ID.

## Response Format

### Review Object Fields

| Field | Type | Description |
| --- | --- | --- |
| id | string | Opaque review identifier; do not parse as a number |
| score | float | Review score (1-10 scale) |
| reviewed\_date | string | Review timestamp (YYYY-MM-DD HH:MM:SS, UTC) |
| hotelier\_name | string | Nullable reply-author name; null when unavailable |
| is\_incentivised | boolean | null | Whether review was incentivised; null when unknown |
| guest (object) |
| guest.name | string | Reviewer's name |
| guest.avatar | string | Reviewer's profile picture URL |
| guest.nr\_reviews | integer | null | Available reviewer review count, or null; may differ from historical counts |
| guest.country | string | Country code (uppercase) |
| guest.country\_code | string | Country code (e.g., "th") |
| guest.traveler\_type | string | Type of traveler (Solo, Couple, Family, etc.) |
| guest.anonymous | boolean | Whether review is anonymous |
| stay\_details (object) |
| stay\_details.room\_type | string | Name of the room type booked |
| stay\_details.nights | integer | Number of nights stayed |
| stay\_details.checkin | string | null | Included only with include\_stay\_dates=true. Check-in date (YYYY-MM-DD), or null when unavailable. |
| stay\_details.checkout | string | null | Included only with include\_stay\_dates=true. Check-out date (YYYY-MM-DD), or null when unavailable. |
| review (object) |
| review.title | string | Review title/summary (may be null) |
| review.positive | string | Positive aspects mentioned (may be null) |
| review.negative | string | Negative aspects mentioned (may be null) |
| review.language | string | Review language code |
| Additional fields |
| helpful\_votes | integer | Number of helpful votes |
| has\_photos | boolean | Whether the reviewer uploaded photos |
| photos | array | Reviewer-uploaded photo URLs |
| partner\_reply | string | Hotel response (may be null) |

#### Pagination

Use the pagination object to implement proper pagination in your application. Large hotels may have thousands of reviews.

#### Zero reviews versus an invalid ID

A valid Booking.com property with no reviews returns HTTP 200 with reviews\_returned: 0 and an empty reviews array. A numeric hotel\_id that does not exist returns HTTP 404 with error\_code NOT\_FOUND. When the hotel has reviews but none match an explicit language filter, the first page returns NO\_MATCHING\_REVIEWS.

## Error handling and status codes

**Status codes:** 200 on success; errors use non-2xx (400, 404, 500, 502, 503, 504) with Problem Details.

- **400** `INVALID_HOTEL_ID`: Input validation failed (hotel\_id must be a numeric string).
- **404** `NOT_FOUND`: The numeric hotel\_id does not identify a Booking.com property. Valid zero-review properties return 200 with an empty result.
- **502** `UPSTREAM_ERROR`: Booking.com could not complete the request.
- **503** Service Unavailable: Upstream rate-limited/maintenance (may include `Retry-After`).
- **504** Upstream Timeout: The provider timed out.
- **500** `CONTENT_EXTRACTION_FAILED` or `INTERNAL_ERROR`: Unexpected parsing/processing errors.

### Error responses (Problem Details)

All Booking.com hotel endpoints return errors using RFC 7807 Problem Details.

```
{
  "type": "https://api.stayapi.com/errors/invalid-url",
  "title": "Invalid URL",
  "status": 400,
  "detail": "Parameter 'url' must be a full Booking.com hotel URL of the form https://www.booking.com/hotel/{cc}/{slug}.html.",
  "error_code": "INVALID_URL",
  "provided": "baan-coconut"
}
```

**Media type:** `application/problem+json`

**Standard fields:** `type`, `title`, `status`, `detail`

**Extensions:** `error_code` and any endpoint-specific fields

**2xx policy:** 2xx is returned only when data extraction succeeds.

Request

```curl
# Example request
curl -X GET "https://api.stayapi.com/v1/booking/hotel/reviews?hotel_id=1302021&page=1&per_page=10&language=en" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Without language filter
curl -X GET "https://api.stayapi.com/v1/booking/hotel/reviews?hotel_id=1302021&page=1&per_page=25" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Newest-first for date-range backfill (e.g. last 12 months)
# Paginate page=1,2,3... and stop when reviewed_date < your cutoff
curl -X GET "https://api.stayapi.com/v1/booking/hotel/reviews?hotel_id=1302021&sort=recent_desc&per_page=25&page=1" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

Response

```json
{
  "success": true,
  "hotel_id": "1302021",
  "data": {
    "reviews_returned": 1,
    "reviews": [
      {
        "id": "879a6d0c104fafb9",
        "score": 9.0,
        "reviewed_date": "2026-11-01 12:00:00",
        "hotelier_name": null,
        "is_incentivised": null,
        "guest": {
          "name": "Sophie M.",
          "avatar": "https://cf.bstatic.com/avatar/s1.png",
          "nr_reviews": 12,
          "country": "FR",
          "country_code": "fr",
          "traveler_type": "Couple",
          "anonymous": false
        },
        "stay_details": {
          "room_type": "Deluxe Bungalow",
          "nights": 5
        },
        "review": {
          "title": "Exceptional luxury experience",
          "positive": "The service was impeccable and the location is perfect.",
          "negative": null,
          "language": "en"
        },
        "helpful_votes": 3,
        "has_photos": true,
        "photos": ["https://cf.bstatic.com/review_photo.jpg"],
        "partner_reply": "Thank you for your kind review!"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "has_next_page": true,
      "has_previous_page": false
    }
  },
  "message": "Success",
  "retrieved_at": "2026-01-19T15:00:00Z"
}
```

```json
{
  "type": "https://api.stayapi.com/errors/invalid-hotel-id",
  "title": "Invalid Hotel ID",
  "status": 400,
  "detail": "Parameter 'hotel_id' must be a numeric string.",
  "instance": "/v1/booking/hotel/reviews",
  "provider": "booking",
  "error_code": "INVALID_HOTEL_ID"
}
```