# Displaying attraction reviews and scores 3.2 Beta

**Best practices for presenting attraction reviews and scores retrieved via Booking.com's Demand API.**

## Reviews and scores

Reviews provide detailed traveller feedback, helping users understand what to expect, compare experiences, and make informed decisions.

Review scores summarise traveller feedback, allowing quick comparison of attractions. Scores are broken down by categories such as accessibility, facilities, service quality, and value for money.

Important
The scores reflect feedback from all Booking.com travellers and may not correspond directly to your own users’ experiences.
If you choose to display or use these ratings and reviews, ensure your travellers understand their origin and context.

### Endpoint /attractions/reviews

Use this endpoint to retrieve detailed reviews for a single attraction, supporting language filtering and pagination.

#### Request parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `attraction` | string | Yes | Unique identifier of the attraction. |
| `language` | string | No | IETF BCP 47 language code for the review content (e.g., `en-gb`). |
| `rows` | integer | No | Number of reviews per request (10–100, default 10). Must be a multiple of 10. |


Example request:

```json
{
  "attraction": "PRTcWzDlwXjP",
  "language": "en-gb",
  "rows": 10
}
```

#### Example response

```json
{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "attraction": "PRTcWzDlwXjP",
      "id": "review123456",
      "author": "John D.",
      "author_country_code": "us",
      "rating": 5,
      "text": "Amazing experience at the museum. The artwork is incredible...",
      "language": "en-gb",
      "date": "2025-08-15"
    }
  ],
  "metadata": {
    "next_page": "NextPageToken123",
    "total_results": 243
  }
}
```

> ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) **Reccommendation:**
* **Few Reviews** - Display partial feedback when review counts are low (e.g., fewer than 3–5 reviews). Use visual cues like stars or snippets.
* **No reviews** - Display a “No reviews yet” message. Optionally invite users to submit a review.



### Endpoint /attractions/reviews/scores

Use this endpoint to retrieve aggregated review scores for one or more attractions, ideal for summarising ratings without showing full review text.

#### Request parameters

| Parameter | Required | Description |
|  --- | --- | --- |
| `attractions` | Yes | Unique identifiers of the attractions to retrieve scores for. Maximum 1 per request. |


Example:

```json
POST /attractions/reviews/scores
Headers:
  X-Affiliate-Id: 123456
Body:
{
  "attractions": ["PRTcWzDlwXjP"]
}
```

#### Example response

A typical attraction:

```json
{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": "PRTcWzDlwXjP",
      "breakdown": {
        "easy_to_access": {"number_of_reviews": 182, "score": 4.5},
        "facilities_rating": {"number_of_reviews": 160, "score": 4.7},
        "quality_of_service": {"number_of_reviews": 175, "score": 4.6},
        "value_of_experience": {"number_of_reviews": 187, "score": 4.8}
      }
    }
  ]
}
```

> ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) **Few reviews / new attraction:**
* Display scores only if there is a minimum number of reviews (e.g., ≥3) to avoid misleading users.
* For zero reviews, show “No scores available yet.”



## Display recommendations

### Reviews content

* **Author and country** - Show the reviewer’s name and country to provide context.
* **Rating** - Use a consistent visual representation (e.g., star icons or bars).
* **Text content** - Limit the initial visible text and provide a “Read more” option to reduce cognitive load.
* **Date** - Show the date of submission to indicate relevance.
* **Language** - Display if your users navigate multilingual content.
* **Disclaimer** - Always indicate that the scores come from Booking.com travellers.


### Score content

* **Category breakdowns** - Display each score clearly, e.g., accessibility, facilities, service, value.
* **Number of reviews** - Show counts per category to provide context.
* **Average score** - Present visually with stars, bars, or a radar chart.
* **Zero-review handling** - Display a clear “No scores yet” message.


### Pagination & performance

* **Lazy Loading** - Load additional reviews only when the user requests more, avoiding heavy initial payloads.
* **Fetch only what’s necessary** - For search/listing pages, consider fetching only summary scores or top review excerpts.
* Handle `next_page` tokens to retrieve additional reviews efficiently.
* Store responses where appropriate to reduce API calls and improve perceived performance.


## Search & look flow recommendations

**Search/listing pages:**

* Display only overall average score or a visual badge.
* Avoid showing detailed breakdowns to reduce cognitive load.


**Detail pages:**

* Show full category breakdowns with number of reviews.
* Allow users to click through to full reviews (linking to /attractions/reviews).


## Summary

| Endpoint | Action |
|  --- | --- |
| /attractions/reviews
 | ✓ Enhance attraction pages with traveller feedback.
✓ Support both search/listing and detailed attraction flows.
✓ Present ratings and reviews clearly and accessibly.
✓ Handle varying review volumes gracefully.
 |
| /attractions/reviews/scores
 | ✓ Display structured ratings for attractions in a clear, engaging way.
✓ Provide quick comparison for search/listing flows.
✓ Enhance attraction detail pages with category-level insights.
✓ Handle varying review volumes gracefully and maintain UX consistency.
 |


Curious to know more?
- Explore the [Search for attractions](/demand/docs/attractions/search-attractions) guide for search requests.
- Learn about the [Attraction details endpoint](/demand/docs/attractions/display-attraction-details) for full content.
- See tha [Attractions API reference here](/demand/docs/open-api/3.2-beta/demand-api/attractions) for all endpoints and schemas.