GET
# Hotel Reviews Summary API

Get review metadata including total count, language breakdown, traveler types, and topics for any Booking.com hotel.

## Overview

#### Accurate Total Counts

This endpoint provides accurate total review counts and breakdowns that are not available from the reviews endpoint.

The Hotel Reviews Summary endpoint provides review metadata including the total review count, breakdown by language, traveler type, and popular topics mentioned in reviews.

### Endpoint URL

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

## 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`: The hotel\_id parameter is missing or not a valid numeric ID.
- **404** `NOT_FOUND`: The numeric hotel\_id does not identify a Booking.com property. Valid zero-review properties return 200 with `total_reviews: 0` and empty breakdowns.
- **502** `UPSTREAM_ERROR`: Review data is unavailable or inconsistent.
- **503** Service Unavailable: Upstream rate-limited/maintenance (may include `Retry-After`).
- **504** Upstream Timeout: The provider timed out.
- **500** `INTERNAL_ERROR`: Unexpected 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.

## Query Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| hotel\_id | string | Required | Booking.com hotel ID (numeric string, e.g., "1302021") |

#### Getting the Hotel ID

You can get the hotel\_id from the /v1/booking/hotel/details endpoint response.

## Response Structure

### Summary Data

- `total_reviews` - Total number of reviews for this hotel
- `languages` - Breakdown by language, combining regional variants (array of name/count)
- `traveler_types` - Available categories: Couple, Family, Group of friends, Solo traveler (array of name/count); no separate business category
- `topics` - Up to ten property-specific topics (array of name/count); topics may overlap

#### Zero reviews versus an invalid ID

A valid Booking.com property with no reviews returns HTTP 200 with total\_reviews: 0 and empty language, traveler-type, and topic arrays. A numeric hotel\_id that does not exist returns HTTP 404 with error\_code NOT\_FOUND.

## Usage Examples

### Input requirement

Provide the numeric Booking.com hotel ID in the `hotel_id` parameter. Example: `1302021`

#### Performance Tip

Use this endpoint when you need accurate total counts or review breakdowns. For individual reviews, use the /hotel/reviews endpoint.

Request

```curl
curl -X GET "https://api.stayapi.com/v1/booking/hotel/reviews/summary?hotel_id=1302021" \
  -H "x-api-key: YOUR_API_KEY"
```

Response

```json
{
  "success": true,
  "hotel_id": "1302021",
  "data": {
    "total_reviews": 60,
    "languages": [
      {"name": "English", "count": 31},
      {"name": "Russian", "count": 16},
      {"name": "Chinese", "count": 8},
      {"name": "German", "count": 5}
    ],
    "traveler_types": [
      {"name": "Couple", "count": 25},
      {"name": "Family", "count": 18},
      {"name": "Solo traveler", "count": 10},
      {"name": "Group of friends", "count": 7}
    ],
    "topics": [
      {"name": "Beach", "count": 15},
      {"name": "Room", "count": 12},
      {"name": "Staff", "count": 10},
      {"name": "Pool", "count": 8}
    ]
  },
  "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/summary",
  "provider": "booking",
  "error_code": "INVALID_HOTEL_ID"
}
```