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.

Endpoint /attractions/reviews

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

Request parameters

Example request:

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

Example response

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

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

Example:

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

Example response

A typical attraction:

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

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