GET

Hotel Reviews API

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

Copy for your AI agent

Paste into Claude, ChatGPT, Cursor or Copilot — endpoint, parameters, response fields and a curl example in Markdown.

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

# 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"

// Example request
const response = await fetch("https://api.stayapi.com/v1/booking/hotel/reviews?" +
  new URLSearchParams({
    hotel_id: "1302021",
    page: 1,
    per_page: 10,
    language: "en"
  }), {
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(`Found ${data.data.reviews_returned} reviews`);
console.log(`Has next page: ${data.data.pagination.has_next_page}`);

// Display first few reviews with nested structure
data.data.reviews.slice(0, 3).forEach(review => {
  console.log(`${review.guest.name} (${review.score}/10): ${review.review.title}`);
  console.log(`  Room: ${review.stay_details.room_type}`);
});

import requests

url = "https://api.stayapi.com/v1/booking/hotel/reviews"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Example request
params = {
    "hotel_id": "1302021",
    "page": 1,
    "per_page": 10,
    "language": "en"
}

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

if response.status_code == 200:
    print(f"Found {data[\"data\"][\"reviews_returned\"]} reviews on this page")
    print(f"Has next page: {data[\"data\"][\"pagination\"][\"has_next_page\"]}\n")

    for review in data["data"]["reviews"][:3]:
        print(f"{review[\"guest\"][\"name\"]} ({review[\"score\"]}/10):")
        print(f"  Title: {review[\"review\"][\"title\"]}")
        print(f"  Room: {review[\"stay_details\"][\"room_type\"]}\n")

<?php
$url = "https://api.stayapi.com/v1/booking/hotel/reviews";
$params = http_build_query([
    "hotel_id" => "1302021",
    "page" => 1,
    "per_page" => 10,
    "language" => "en"
]);

$headers = [
    "x-api-key: YOUR_API_KEY",
    "Content-Type: application/json"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "?" . $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

if ($data["success"]) {
    echo "Found " . $data["data"]["reviews_returned"] . " reviews\n";
    echo "Has next page: " . ($data["data"]["pagination"]["has_next_page"] ? "yes" : "no") . "\n\n";

    foreach (array_slice($data["data"]["reviews"], 0, 3) as $review) {
        echo $review["guest"]["name"] . " (" . $review["score"] . "/10): " . $review["review"]["title"] . "\n";
    }
}
?>

require "net/http"
require "uri"
require "json"

uri = URI("https://api.stayapi.com/v1/booking/hotel/reviews")
uri.query = URI.encode_www_form({
  hotel_id: "1302021",
  page: 1,
  per_page: 10,
  language: "en"
})

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request["x-api-key"] = "YOUR_API_KEY"
request["Content-Type"] = "application/json"

response = http.request(request)
data = JSON.parse(response.body)

if response.code == "200"
  puts "Found #{data["data"]["reviews_returned"]} reviews"
  puts "Has next page: #{data["data"]["pagination"]["has_next_page"]}\n\n"

  data["data"]["reviews"].first(3).each do |review|
    puts "#{review["guest"]["name"]} (#{review["score"]}/10): #{review["review"]["title"]}"
  end
else
  puts "Error: #{response.code}"
end

Response

{
  "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"
}

{
  "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"
}