# Booking Hotel Reviews

## Overview

| Property | Value |
|----------|-------|
| **Status** | private |
| **Method** | `GET` |
| **Endpoint** | `/v2/booking/hotel/reviews` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/booking-hotel-reviews |

## Description

Extract guest reviews from any Booking.com hotel listing with scores, sentiment text, reviewer details, and stay information.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/booking/hotel/reviews' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Reviews for Novotel Paris Tour Eiffel (en, most_recent)

```json
[
  {
    "reviewUrl": "a3f7b12e9c08542d",
    "isApproved": true,
    "reviewScore": 9.2,
    "textDetails": {
      "lang": "en",
      "title": "Perfect stay in the heart of Paris",
      "negativeText": "The lift is quite small so carrying large suitcases can be tricky. Noise from the street was audible on lower floors.",
      "positiveText": "The room was beautifully decorated, spotlessly clean, and the bed was incredibly comfortable. The staff went out of their way to recommend local restaurants and arranged a late check-out at no extra charge. Breakfast was fresh and varied every morning."
    },
    "guestDetails": {
      "username": "Sophie L.",
      "anonymous": false,
      "avatarUrl": "https://xx.bstatic.com/static/img/review/avatars/ava-f.png",
      "countryCode": "gb",
      "countryName": "United Kingdom",
      "guestTypeTranslation": "Couple"
    },
    "partnerReply": {
      "reply": "Dear Sophie,\n\nThank you so much for your kind words! We are thrilled to hear you enjoyed your stay with us. We will certainly pass on your compliments to our team. We hope to welcome you back very soon!\n\nWarm regards,\nThe Front Desk Team"
    },
    "reviewedDate": 1760961260,
    "bookingDetails": {
      "roomType": {
        "id": "214587",
        "name": "Superior Double Room"
      },
      "numNights": 5,
      "stayStatus": "stayed",
      "checkinDate": "2026-04-02",
      "checkoutDate": "2026-04-07",
      "customerType": "COUPLES"
    },
    "isTranslatable": false,
    "helpfulVotesCount": 14
  },
  {
    "reviewUrl": "c9d4a87f2b163e50",
    "isApproved": true,
    "reviewScore": 7.5,
    "textDetails": {
      "lang": "en",
      "title": null,
      "negativeText": "The bathroom was a bit dated and the shower pressure was weak. Wi-Fi connection was unstable in the evenings.",
      "positiveText": "Excellent location near the metro, very convenient for visiting the main attractions. The room was a good size for Paris standards."
    },
    "guestDetails": {
      "username": "Marco B.",
      "anonymous": false,
      "avatarUrl": "https://xx.bstatic.com/static/img/review/avatars/ava-m.png",
      "countryCode": "it",
      "countryName": "Italy",
      "guestTypeTranslation": "Solo traveller"
    },
    "partnerReply": null,
    "reviewedDate": 1758247800,
    "bookingDetails": {
      "roomType": {
        "id": "198342",
        "name": "Standard Single Room"
      },
      "numNights": 3,
      "stayStatus": "stayed",
      "checkinDate": "2026-03-15",
      "checkoutDate": "2026-03-18",
      "customerType": "SOLO"
    },
    "isTranslatable": true,
    "helpfulVotesCount": 3
  },
  {
    "reviewUrl": "e1b2c3d4f5a67890",
    "isApproved": true,
    "reviewScore": 10,
    "textDetails": {
      "lang": "en",
      "title": "Absolutely flawless: will definitely return",
      "negativeText": null,
      "positiveText": "Everything was perfect from start to finish. The concierge booked us a table at a Michelin-starred restaurant and even arranged a surprise birthday cake in our room. The spa facilities are outstanding and the pool area is a hidden gem. Can not fault a single thing."
    },
    "guestDetails": {
      "username": "Amelia W.",
      "anonymous": false,
      "avatarUrl": "https://xx.bstatic.com/static/img/review/avatars/ava-f.png",
      "countryCode": "au",
      "countryName": "Australia",
      "guestTypeTranslation": "Couple"
    },
    "partnerReply": {
      "reply": "Dear Amelia,\n\nWe are absolutely delighted to read your glowing review! It was truly our pleasure to celebrate such a special occasion with you. Your kind words will be shared with the entire team. We look forward to welcoming you back to Paris very soon!\n\nWith warmest regards,\nThe Management"
    },
    "reviewedDate": 1755532400,
    "bookingDetails": {
      "roomType": {
        "id": "301124",
        "name": "Junior Suite with City View"
      },
      "numNights": 5,
      "stayStatus": "stayed",
      "checkinDate": "2026-02-10",
      "checkoutDate": "2026-02-15",
      "customerType": "COUPLES"
    },
    "isTranslatable": false,
    "helpfulVotesCount": 27
  }
]
```

## Documentation

## Overview
The Booking Hotel Reviews endpoint extracts structured guest reviews from any Booking.com hotel page. For a given hotel URL, it returns scores, positive and negative feedback text, reviewer profiles, stay details, and official hotel management replies, all in a clean, ready-to-use JSON format.

## Quickstart
```
GET https://api.piloterr.com/v2/booking/hotel/reviews?query=https://www.booking.com/hotel/fr/novotel-paris-tour-eiffel.html
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full URL of the Booking.com hotel page |
| `language` | string | no | Filter reviews by ISO 639-1 language code (e.g. `en`, `fr`) |
| `sort_by` | string | no | Sorting order: `most_recent` (default), `highest_score`, `lowest_score` |
| `max_results` | integer | no | Maximum number of reviews to return (default `50`, max `1000`) |

## Response fields
| Field | Type | Description |
|---|---|---|
| `reviewScore` | number | Guest score from 1.0 to 10.0 |
| `reviewedDate` | number | Unix timestamp of review submission |
| `isApproved` | boolean | Whether the review is published by Booking.com moderation |
| `isTranslatable` | boolean | Whether the review content can be machine-translated |
| `helpfulVotesCount` | number | Number of guests who marked this review as helpful |
| `reviewUrl` | string | Internal identifier or relative URL of the review |
| `textDetails.title` | string | Optional reviewer-written title (`null` if absent) |
| `textDetails.positiveText` | string | Positive free-text feedback |
| `textDetails.negativeText` | string | Negative free-text feedback (`null` if none) |
| `textDetails.lang` | string | ISO 639-1 language code of the review text |
| `guestDetails.username` | string | Display name of the reviewer |
| `guestDetails.countryName` | string | Country of origin (e.g. `France`) |
| `guestDetails.countryCode` | string | ISO 3166-1 alpha-2 country code |
| `guestDetails.guestTypeTranslation` | string | Travel group type (e.g. `Couple`, `Solo traveller`) |
| `guestDetails.anonymous` | boolean | Whether the reviewer chose to remain anonymous |
| `guestDetails.avatarUrl` | string | URL of the reviewer's avatar image |
| `bookingDetails.checkinDate` | string | Check-in date in `YYYY-MM-DD` format |
| `bookingDetails.checkoutDate` | string | Check-out date in `YYYY-MM-DD` format |
| `bookingDetails.numNights` | number | Total number of nights stayed |
| `bookingDetails.customerType` | string | Guest category code (`SOLO`, `COUPLES`, `FAMILY`, `GROUP`) |
| `bookingDetails.stayStatus` | string | Confirmation that the stay occurred (e.g. `stayed`) |
| `bookingDetails.roomType.name` | string | Name of the room type booked |
| `bookingDetails.roomType.id` | string | Internal Booking.com room type identifier |
| `partnerReply.reply` | string | Hotel management's official response (`null` if none) |

## Notes
- The `query` parameter must be a full Booking.com hotel URL, not a search results page.
- Reviews are filtered to approved content only (`isApproved: true`).
- The `language` filter limits results to a specific language; omit it to receive reviews in all languages.
- Setting `max_results` above 100 significantly increases response time.

## Main use cases
- Monitor guest sentiment for competitor hotels and benchmark your property against market leaders
- Build sentiment analysis pipelines to track review trends and score evolution over time
- Collect multilingual review datasets for NLP training and hospitality research
- Power hotel comparison tools and travel recommendation engines with real guest feedback
- Automate reputation management workflows by detecting negative reviews that require management response