GET /v1/hotels/{hotelId}/reviews
Guest reviews for a hotel, newest first: rating, pros, cons and the provider. Filter by topic with ?topics=breakfast,pool and by cohort with ?guest-type=. Quote a review against metadata.totalCandidates, and cite metadata.matchedTerms for the word actually matched.
Operation ID: getHotelReviews
Parameters
| Name | In | Type | Required | Constraints | Description |
|---|---|---|---|---|---|
hotelId |
path | integer | yes | 1..9007199254740991 | The hotel’s numeric id (a positive integer), as carried by hotel search results (results[].hotelId) and embedded in a rate id. |
page |
query | integer | no | 1..100; default 1 |
Page number, 1-based (max 100). Defaults to 1. |
pageSize |
query | integer | no | 1..50; default 10 |
Reviews per page (1-50). Defaults to 10. |
sort |
query | posted_at_desc | rating_desc | rating_asc |
no | default "posted_at_desc" |
Sort order. posted_at_desc (default, newest first) – a review corpus answers ‘what is it like now’, so recency opens; rating_desc / rating_asc sort by the provider’s rating. |
locale |
query | string | no | length 1..35; default "en" |
Response language tag (e.g. en, ar). Defaults to en. |
topics |
query | string[] | no | items 1..* | Optional topic terms to filter reviews by (repeat or comma-separate, OR’d together) – e.g. ?topics=breakfast,pool keeps reviews mentioning either. metadata.matchedTerms reports the variants actually matched (breakfast, Breakfast). |
guest-type |
query | couple | family_with_children | solo_traveller | extended_group |
no | - | Optional reviewer-cohort filter: couple, family_with_children, solo_traveller or extended_group. |
view |
query | default | detail |
no | default "default" |
Response projection. default: rating, title, pros, cons, provider. detail: adds the reviewer’s country code and neutral prose notes. Defaults to default. |
Responses
| Status | Description |
|---|---|
200 |
One page of guest reviews. |
400 |
Invalid request parameters. |
401 |
Missing or invalid bearer token. |
404 |
Unknown hotel. |
429 |
Rate limit exceeded; retry after the Retry-After seconds. |
502 |
The upstream hotels service returned an invalid response. |
503 |
The hotels service is unavailable (upstream_unavailable) or rate-limited upstream (upstream_rate_limited); retry after the Retry-After seconds. |
200 body
| Field | Type | Always present | Description |
|---|---|---|---|
hotelId |
number | yes | The hotel these reviews are for. |
metadata |
object | yes | Pagination and the matched-topic accounting for this reviews read. |
↳ page |
integer | yes | 1-based page number of this read. |
↳ pageSize |
integer | yes | Reviews requested per page. |
↳ resultCount |
integer | yes | Reviews on this page. |
↳ totalCandidates |
integer | no | Reviews matching this read’s filters across ALL pages – the denominator to quote a review against (‘15 of 141’). It is the FILTERED total, so an unfiltered read is needed to state the hotel’s full review count. EXACT only when hasMore is false: when hasMore is true this can be a LOWER BOUND, because an upstream page that carries no count of its own falls back to the offset plus the rows it sent, so quote it as ‘at least N’. ABSENT when this read establishes no total at all – an empty page past the first whose upstream sent no count says nothing about the pages before it. Absent means UNKNOWN, never zero: re-read page 1 before reporting any number. |
↳ hasMore |
boolean | yes | Another page may follow. A full page always sets this, count or no count. While it is true, read totalCandidates as a floor rather than a corpus size. |
↳ topics |
string[] | yes | The topic terms this read asked for. |
↳ matchedTerms |
string[] | yes | The term variants the upstream actually matched (e.g. breakfast, Breakfast). Empty on an unfiltered read. Cite from here rather than from topics, so a quote states the word that was really found. |
results |
object[] | yes | The requested page of guest reviews. |
↳ rating |
number | yes | The provider’s own 0–10 rating for this review, passed through. |
↳ title |
string | no | Review title, when the guest gave one. |
↳ postedAt |
string | yes | Calendar date (YYYY-MM-DD). |
↳ providerCode |
string | yes | Which provider collected the review (e.g. booking.com). |
↳ guestType |
couple | family_with_children | solo_traveller | extended_group |
no | The reviewer’s cohort, normalized onto the closed set. Omitted when the upstream sent a value outside it. |
↳ pros |
string[] | yes | What the guest liked, verbatim. |
↳ cons |
string[] | yes | What the guest disliked, verbatim. |
↳ notes |
string[] | no | view=detail only – review prose the provider tagged neither positive nor negative. |
↳ countryCode |
string | no | view=detail only – the reviewer’s country code. The reviewer’s name is never returned. |
Example
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.wego.com/v1/hotels/$HOTEL_ID/reviews"