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
url string Required Full Booking.com hotel URL (https://www.booking.com/hotel/{cc}/{slug}.html)
page integer Optional Page number for pagination (default: 1)
per_page integer Optional Number of reviews per page (default: 20, max: 50)
language string Optional Filter reviews by language (e.g., "en", "fr", "es")
sort string Optional Sort order: "newest", "oldest", "rating_high", "rating_low" (default: "newest")

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

Response Format

Review Object Fields

Field Type Description
id string Unique review identifier
author string Reviewer name (anonymized)
country string Reviewer's country
rating integer Review rating (1-10 scale)
title string Review title/summary
text string Full review text
date string Review date (ISO 8601 format)
helpful_votes integer Number of helpful votes received

Pagination

Use the pagination object to implement proper pagination in your application. Large hotels may have thousands of 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_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.

Request
# Example request
curl -X GET "https://api.stayapi.com/v1/booking/hotel/reviews?url=https%3A%2F%2Fwww.booking.com%2Fhotel%2Fth%2Fbaan-coconut.html&page=1&per_page=20&sort=newest&language=en" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Using full URL
curl -X GET "https://api.stayapi.com/v1/booking/hotel/reviews?url=https%3A%2F%2Fwww.booking.com%2Fhotel%2Ffr%2Fle-grand-hotel-paris.html&page=1&per_page=20" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
Response
{
  "status": "success",
  "data": {
    "hotel_name": "Le Grand Hotel InterContinental",
    "total_reviews": 2847,
    "average_rating": 8.6,
    "rating_breakdown": {
      "10": 856,
      "9": 712,
      "8": 634,
      "7": 387,
      "6": 145,
      "5": 78,
      "4": 23,
      "3": 8,
      "2": 3,
      "1": 1
    },
    "reviews": [
      {
        "id": "review_789",
        "author": "Sophie M.",
        "country": "France",
        "rating": 9,
        "title": "Exceptional luxury experience",
        "text": "The service was impeccable and the location is perfect for exploring Paris. The rooms are beautifully decorated and the breakfast was outstanding. Staff went above and beyond to make our anniversary special.",
        "date": "2024-02-15",
        "helpful_votes": 12,
        "language": "en",
        "verified_stay": true,
        "room_type": "Deluxe Suite",
        "travel_type": "Couple",
        "photos": [
          "https://images.booking.com/review_123.jpg"
        ]
      },
      {
        "id": "review_790",
        "author": "James D.",
        "country": "United Kingdom",
        "rating": 8,
        "title": "Great location, excellent service",
        "text": "Perfect location in the heart of Paris. The concierge was extremely helpful with restaurant recommendations. Room was spacious and clean.",
        "date": "2024-02-12",
        "helpful_votes": 8,
        "language": "en",
        "verified_stay": true,
        "room_type": "Standard Double",
        "travel_type": "Business",
        "photos": []
      },
      {
        "id": "review_791",
        "author": "Maria S.",
        "country": "Spain",
        "rating": 10,
        "title": "Perfección absoluta",
        "text": "Todo fue perfecto desde el check-in hasta el check-out. El personal es muy profesional y atento. Las habitaciones son elegantes y muy cómodas.",
        "date": "2024-02-10",
        "helpful_votes": 15,
        "language": "es",
        "verified_stay": true,
        "room_type": "Premium Room",
        "travel_type": "Family",
        "photos": [
          "https://images.booking.com/review_456.jpg",
          "https://images.booking.com/review_457.jpg"
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_pages": 143,
      "has_next": true,
      "has_previous": false
    }
  }
}