GET

Hotel Review Scores API

Get aggregated review scores by category and traveler type for any Booking.com hotel.

Overview

Detailed Score Breakdown

This endpoint provides category-level scores (staff, cleanliness, comfort, etc.) and per-traveler-type breakdowns that are not available from the reviews or summary endpoints.

The Hotel Review Scores endpoint returns the overall score, individual category scores on a 1-10 scale, score distribution, and a breakdown by traveler type (family, couple, solo, group, business).

Endpoint URL

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

Query Parameters

Parameter	Type	Required	Description
hotel_id	string	Required	Booking.com hotel ID (numeric string, e.g., "224399")

Getting the Hotel ID

Use the /v1/booking/hotel/url-to-id endpoint to convert a Booking.com URL or slug to a numeric hotel ID.

Response Structure

Scores

scores.overall - Overall review score (1-10 scale)
scores.staff - Staff score
scores.cleanliness - Cleanliness score
scores.comfort - Comfort score
scores.facilities - Facilities score
scores.location - Location score
scores.value_for_money - Value for money score
scores.wifi - WiFi score

Other Fields

total_reviews - Total number of reviews
score_distribution - Distribution of scores by bucket (may be null)
score_percentage - Percentage breakdown by label (may be null)

Traveler Type Breakdown

scores_by_traveler_type[].type - Traveler type (e.g., "solo_traveller", "review_adjective_group_of_friends")
scores_by_traveler_type[].overall - Overall score for this traveler type
scores_by_traveler_type[].count - Number of reviews from this type
scores_by_traveler_type[].scores - Per-category scores for this type

Usage Examples

Input requirement

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

Use Case

This endpoint is ideal for building comparison dashboards or tracking score trends across categories and traveler segments.

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.
502 UPSTREAM_ERROR: Upstream non-2xx or API errors.
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.

Request

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

const response = await fetch(
  "https://api.stayapi.com/v1/booking/hotel/reviews/scores?hotel_id=224399",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(`Overall: ${data.data.scores.overall}`);
console.log(`Staff: ${data.data.scores.staff}`);

import requests

url = "https://api.stayapi.com/v1/booking/hotel/reviews/scores"
headers = {"x-api-key": "YOUR_API_KEY"}
params = {"hotel_id": "224399"}

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

scores = data["data"]["scores"]
print(f"Overall: {scores['overall']}")

# Print traveler breakdown
for t in data["data"]["scores_by_traveler_type"]:
    print(f"{t['type']}: {t['overall']} ({t['count']} reviews)")

Response

{
  "success": true,
  "hotel_id": "224399",
  "data": {
    "scores": {
      "overall": 8.0,
      "cleanliness": 8.4,
      "staff": 8.5,
      "comfort": 8.3,
      "facilities": 8.1,
      "location": 9.3,
      "value_for_money": 7.6,
      "wifi": 5.6
    },
    "total_reviews": 12614,
    "score_distribution": null,
    "score_percentage": null,
    "scores_by_traveler_type": [
      {
        "type": "solo_traveller",
        "overall": 7.9,
        "count": 1258,
        "scores": {
          "cleanliness": 8.3,
          "staff": 8.4,
          "comfort": 8.2,
          "facilities": 8.0,
          "location": 9.3,
          "value_for_money": 7.5,
          "wifi": 5.5
        }
      },
      {
        "type": "review_adjective_couple",
        "overall": 8.1,
        "count": 4202,
        "scores": {
          "cleanliness": 8.5,
          "staff": 8.5,
          "comfort": 8.4,
          "facilities": 8.2,
          "location": 9.3,
          "value_for_money": 7.7,
          "wifi": 5.6
        }
      }
    ]
  },
  "message": "Success",
  "retrieved_at": "2026-03-02T12:00:00Z"
}

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