Fetch Reviews

The Reviews endpoint retrieves reviews for a specific hotel.

GET https://api.rateparity.com/v1/reviews/{code}

Query Parameters

Filtering is supported to refine the results based on the below criteria.

Name	Type	Description
category	Category Type	Filters reviews based on the review category
score	Score Type	Filters reviews by review score: SUPERB (9-10), GOOD (7-8), PASSABLE (5-6), POOR (3-4), and VERYPOOR (1-2).
country	string	Filters reviews based on the reviewer's country.
reviewerLanguages	List	Filters reviews based on the language of the review content.
season	Season Type	Filters reviews according to the season or time of year.
verbose	boolean	To include additional information when set to true (default: false).

Pagination

See Pagination for more details. Sorting options are dateReviewed, mostRelevant and score.

Model Description

See Model Description for the base structure of responses.

Data Object Fields

The data object contains the primary response information returned by the API:

Name	Type	Description
channels	List of ReviewScore objects	Review scores and details from Airbnb.
score	double	The overall average score calculated from all available sources.
reviews	integer	Total number of reviews aggregated across all sources.
timeUpdated	Instant	The timestamp of the last update.
userReviews	List of ReviewDetails objects	A list of individual user reviews with details such as reviewer name, score, title, description, and review date.
facilities	List of ReviewFacility objects	A list of facilities mentioned in reviews. If null, no facilities data is available.

ReviewScore Object Fields

The ReviewScore object represents the scoring details for each review source:

Name	Type	Description
title	String	The channel name.
score	double	The average review score from the source.
outOfScore	integer	The maximum possible score for the source (e.g., 10 or 6).
total	integer	The total number of reviews counted for this source.

ReviewDetails Object Fields

Name	Type	Description
name	string	Name of the reviewer.
category	string	Category of the reviewer (e.g., Solo traveller, Family, etc.).
dateReviewed	Date	The date the review was submitted.
score	double	The review score provided by the user.
title	string	Title of the review.
description	string	Detailed text of the review.
country	string	Country of the reviewer.
language	string	Language of the review.
photoUrl	string	URL to the reviewer's photo, if available.
channel	string	The source channel of the review (e.g. Booking.com, Tripadvisor.com).
hidden	boolean	Indicates if the review is hidden (true) or visible (false).

ReviewFacility Object Fields

Name	Type	Description
channel	string	The source channel of the review (e.g., Booking.com, Tripadvisor.com).
facility	string	The name of the facility mentioned in the review.
score	double	The review score related to the facility.
timestamp	Date	The date and time when the facility was reviewed.

MetaData Object Fields

Name	Type	Description
countries	Map<String, String>	The countries available for filtering.
filterTotals	FilterTotals object	The filtering options totals.
sortingOptions	List	Available options for sorting.

FilterTotals Object Fields

Name	Type	Description
categories	Map<Category, Integer>	The Category Type totals.
scores	Map<Score, Integer>	The Score Type totals.
seasons	Map<Season, Integer>	The Season Type totals.

Request Example

curl --location 'https://api.rateparity.com/v1/review/{code}?limit=10&page=1&sort=dateReviewed&asc=false&country=Italy&reviewerLanguages=en,it' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {JWT_TOKEN}'

200 OK - Success

{
  "data": {
    "channels": [
      {
        "title": "airbnb",
        "score": 10.0,
        "outOfScore": 10,
        "total": 16
      },
      {
        "title": "booking",
        "score": 9.0,
        "outOfScore": 10,
        "total": 367
      },
      {
        "title": "expedia",
        "score": 0.0,
        "outOfScore": 10,
        "total": 0
      },
      {
        "title": "google",
        "score": 9.6,
        "outOfScore": 10,
        "total": 85
      },
      {
        "title": "holidayCheck",
        "score": 0.0,
        "outOfScore": 6,
        "total": 0
      },
      {
        "title": "hotels",
        "score": 0.0,
        "outOfScore": 10,
        "total": 0
      },
      {
        "title": "tripadvisor",
        "score": 0.0,
        "outOfScore": 10,
        "total": 0
      }
    ],
    "score": 9.53,
    "reviews": 468,
    "timeUpdated": "2025-04-01T00:44:37Z",
    "userReviews": [
      {
        "id": 550942,
        "name": "Wifak",
        "category": "Couple",
        "dateReviewed": "2025-03-21T00:00:00.000+00:00",
        "score": 10.0,
        "title": "Exceptional",
        "description": "There are no comments available for this review",
        "country": "Italy",
        "language": "en",
        "photoUrl": "",
        "channel": "Booking.com",
        "hidden": false
      },
      {
        "id": 537153,
        "name": "Schenatti",
        "category": "Group",
        "dateReviewed": "2025-02-24T00:00:00.000+00:00",
        "score": 9.0,
        "title": "Superb",
        "description": "There are no comments available for this review",
        "country": "Italy",
        "language": "en",
        "photoUrl": "",
        "channel": "Booking.com",
        "hidden": false
      },
      {
        "id": 510078,
        "name": "Cinzia",
        "category": "Couple",
        "dateReviewed": "2025-01-06T00:00:00.000+00:00",
        "score": 9.0,
        "title": "Superb",
        "description": "Colazione esterna in un bel locale a pochi minuti a piedi, possibilità di scelta di 4 menu per tutti i gusti, buono tutto e abbondante. Il proprietario super ospitale e disponibile per ogni evenienza e consiglio. Nella camera c'è anche una cucina che noi non abbiamo usato ma super utile. Posizione strategica per raggiungere a piedi il tutto!",
        "language": "it",
        "country": "Italy",
        "photoUrl": "",
        "channel": "Booking.com",
        "hidden": false
      },
      {
        "id": 460086,
        "name": "Fabysmile",
        "category": "Couple",
        "dateReviewed": "2024-09-24T00:00:00.000+00:00",
        "score": 10.0,
        "title": "Posizione buonissima",
        "description": "Posizione ottima, stanza pulita e disponibilità dell'host. Spiegazioni accurate per entrare in struttura e per fare il check-in.",
        "language": "it",
        "country": "Italy",
        "photoUrl": "",
        "channel": "Booking.com",
        "hidden": false
      },
      {
        "id": 440578,
        "name": "Alessandro",
        "category": "Solo traveller",
        "dateReviewed": "2024-08-29T00:00:00.000+00:00",
        "score": 9.0,
        "title": "Superb",
        "description": "Struttura nuova accogliente che nel suo iinterno richiama li stile del quartiere in cui si trova ...vengono riprodotte le più belle opere di strettamente art presenti in zona .. stanza pulita ...cucina nuova e pulita ,..staff presente e disponibile ... posizione ottima ...",
        "language": "it",
        "country": "Italy",
        "photoUrl": "",
        "channel": "Booking.com",
        "hidden": false
      }
    ],
    "facilities": [
      {
        "channel": "Booking.com",
        "facility": "staff",
        "score": 9.5
      },
      {
        "channel": "Booking.com",
        "facility": "facilities",
        "score": 9.0
      },
      {
        "channel": "Booking.com",
        "facility": "cleanliness",
        "score": 9.2
      },
      {
        "channel": "Booking.com",
        "facility": "comfort",
        "score": 9.1
      },
      {
        "channel": "Booking.com",
        "facility": "valueformoney",
        "score": 8.9
      },
      {
        "channel": "Booking.com",
        "facility": "location",
        "score": 9.4
      },
      {
        "channel": "Booking.com",
        "facility": "freewifi",
        "score": 9.4
      }
    ]
  }
}

400 Bad Request

401 Unauthorized

{
  "metadata": {
    "timestamp": "2025-02-27T10:54:03.474744"
  },
  "error": {
    "message": "Unauthorized user"
  }
}