GET

Hotel Reviews Summary API

Get aggregated review statistics and summary data for any Booking.com hotel.

Overview

Quick Review Insights

Retrieve comprehensive review statistics without fetching individual reviews.

The Hotel Reviews Summary endpoint provides aggregated review data including total review count, score breakdowns, language distribution, and category ratings for any hotel on Booking.com.

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_URL: Input validation failed (requires full canonical URL).
404 Not Found: Upstream indicates the hotel is missing.
502 UPSTREAM_ERROR: Upstream non-2xx or GraphQL errors.
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.

Query Parameters

Parameter	Type	Required	Description
url	string	Required	Full Booking.com hotel URL (https://www.booking.com/hotel/{cc}/{slug}.html)

Response Structure

Summary Statistics

total_reviews - Total number of reviews
overall_rating - Average rating score (0-10)
rating_distribution - Breakdown by score ranges
language_distribution - Reviews by language

Category Scores

Staff
Facilities
Cleanliness
Comfort
Value for money
Location
Free WiFi

Usage Examples

Input requirement

Provide the full Booking.com hotel URL in the url parameter. Example: https://www.booking.com/hotel/th/baan-coconut.html

Performance Tip

Use this endpoint when you only need aggregated statistics. For individual reviews, use the /hotel/reviews endpoint.

Request

curl -X GET "https://api.stayapi.com/v1/booking/hotel/reviews/summary?url=https://www.booking.com/hotel/th/baan-coconut.html" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.stayapi.com/v1/booking/hotel/reviews/summary?url=https://www.booking.com/hotel/th/baan-coconut.html",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(`Total reviews: ${data.data.total_reviews}`);
console.log(`Overall rating: ${data.data.overall_rating}/10`);

import requests

url = "https://api.stayapi.com/v1/booking/hotel/reviews/summary"
headers = {"x-api-key": "YOUR_API_KEY"}
params = {"url": "https://www.booking.com/hotel/th/baan-coconut.html"}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(f"Total reviews: {data['data']['total_reviews']}")
print(f"Overall rating: {data['data']['overall_rating']}/10")

# Print category scores
for category, score in data["data"]["category_scores"].items():
    print(f"{category}: {score}")

Response

{
  "success": true,
  "data": {
    "total_reviews": 1247,
    "overall_rating": 8.7,
    "rating_word": "Fabulous",
    "rating_distribution": {
      "excellent": 542,
      "very_good": 438,
      "good": 189,
      "okay": 56,
      "poor": 22
    },
    "language_distribution": {
      "English": 645,
      "Thai": 234,
      "Chinese": 156,
      "German": 89,
      "French": 78,
      "other": 45
    },
    "category_scores": {
      "staff": 9.2,
      "facilities": 8.5,
      "cleanliness": 8.9,
      "comfort": 8.7,
      "value_for_money": 8.3,
      "location": 9.1,
      "free_wifi": 8.0
    },
    "traveler_types": {
      "couples": 567,
      "families": 342,
      "solo_travelers": 198,
      "business": 89,
      "groups": 51
    },
    "pros_mentioned": [
      "Great location",
      "Friendly staff",
      "Clean rooms",
      "Good breakfast",
      "Comfortable beds"
    ],
    "cons_mentioned": [
      "Small pool",
      "Limited parking",
      "Noisy at night"
    ]
  },
  "message": "Successfully retrieved review summary",
  "retrieved_at": "2024-01-15T10:30:00Z"
}

{
  "error": "Hotel not found",
  "detail": "Could not find hotel with URL: invalid-hotel",
  "status_code": 404
}