| Method | Path |
|---|---|
GET |
https://agora.olery.com/v3/companies/:id/review_widget |
Returns aggregated data and content to fill the review widget.
Output Format
The aggregated data is returned as an Array of JSON objects in the
data field. Each object has the following fields:
| Field | Data Types | Description |
|---|---|---|
| id | Integer | ID of the property |
| name | String | Name of the property |
| rating | Float | Average overall rating |
| review_count | Integer | Total number of reviews considered |
| updated_at | String | Datetime the cache was updated |
| ratings | Hash | Rating categories and their subratings |
| mentions | Hash | Sentiment opinions |
| guests | Hash | Ratings grouped by the reviewer’s travel composition and country of origin |
| summaries | Hash | Review summaries |
| nearby_attractions | Hash | Relevant nearby attractions |
| nearby_restaurants | Hash | Relevant nearby restaurants |
| recent_reviews | Hash | Recent reviews with opinions and reviewer’s country of origin |
| reviews_over_time | Hash | Review count over month and week periods |
| events | Hash | Covid number of cases over time and per country |
| shifts | Hash | Per week or per month review count difference per reviewer’s travel composition or country of origin |
Ratings
The “ratings” field is an array with all rating categories.
Values for the ratings are integers with a scale of 0 to 100. Rating topics without values are not included in the object.
| count | Integer | Count of ratings |
| review_count | Integer | Count of reviews the ratings came from |
| value | Float | Average rating |
| topic | String | Rating category |
Thev1-backupre can be multiple ratings for the same topic. For this
reason the count and rating_count can differ.
Guests
These ratings are structured as above with the exception that they are grouped by country and travel composition.
Mentions
A review can contain multiple mentions, even of the same topic. Also, we give an overall topic which is a compilation of the opinions per section.
The sentiment score is a float on a scale from -1.0 to 1.0.
A value of -1.0 indicates a completely negative opinion while 1.0
indicates a completely positive opinion. The calculation is
(positive count - negative count) / (positive count + negative count).
| rating | hash | Topic of the rating (category of topics - When available) |
| rating[].key | String | key of the rating |
| rating[].label | String | label of the rating |
| positive_opinions | Integer | Count of positive opinions about the topic |
| negative_opinions | Integer | Count of negative opinions about the topic |
| sentiment_score | Float | Score taking all opinions into account |
| positive_percentage | Float | Simple percentage of positive opinions |
| opinions-count | Integer | Count of all opinions |
| review-count | Integer | Count of reviews the opinions were extracted from |
| topic | String | Sentiment subrating (see page “Sentiment Ratings”). |
Summaries
The summaries consist of an array of statements. The text fields
contains the content of the statement.
Nearby Attractions
It is an array of popular attractions and points of interest nearby the property.
| id | Integer | ID of the attraction |
| name | String | English name |
| distance | Float | Direct distance in km |
| rating | Float | Average overall rating of the attraction |
| review_count | Integer | Count of reviews in the time period |
Recent reviews
The aggregated data is returned as an Array of JSON objects in the
data field. Each object has the following fields:
| Field | Data Types | Description |
|---|---|---|
| review_date | Date | Date on which the review was published (as stated by the source) |
| ratings | Array | Array containing the review ratings |
| opinions | Array | Opinions analysed from the review title and comments |
| sentiment | String | Overall review sentiment |
| country_code | String | Country code of the reviewer |
| country_name | String | Country name of the reviewer |
| travel_composition | String | Travel composition (friends, family, etc) |
Ratings
The ratings field is an array with objects for each subrating.
The rating itself is an integer on a scale of 0 to 100. All ratings
on different scales are normalized into this scale. The “overall”
is the main rating almost all reviews should have. Ratings
without values are not included in the array.
Each subrating is in 1 out of 9 categories. Understand these categories as a suggestion by Olery. You can aggregate the ratings for the categories to make the number of rating topics more manageable for the user.
Fields for each subrating:
| Field | Data Types | Description |
|---|---|---|
| title | String | Human-friendly title of the rating |
| topic | String | Machine name of the rating |
| rating | Integer | Rating value |
| category | String | Suggested category of the rating |
Sentiment
All reviews with written content in the following languages get analyzed for the reviewer’s sentiment:
- English
- German
- French
- Dutch
- Italian
- Spanish
- Portuguese
- Russian
- Danish
- Norwegian
- Swedish
- Arabic
- Simplified Chinese
For an updated list of supported languages, call the following endpoint:
| Method | Path |
|---|---|
GET |
https://agora.olery.com/v3/lexicons/languages |
This analysis happens after the review was captured. The review is immmediatley available in the Review Feed and then gets updated with the sentiment data. This can take a few minutes up to several hours.
Aggregated Sentiment
The sentiment field contains the overall detected sentiment of a
review. This can be any of the following values:
- positive
- negative
- neutral
This field is left empty if no sentiment could be detected.
The sentiment_score field contains a score indicating the sentiment
value on a scale from -1 to 1. A score of -1 means a review is 100%
negative, a score of 1 means a review is 100% positive. A review with
a score between 0.0 and 0.5 is considered to be neutral.
sentiment_score is also considering sentiment for which an opinion
topic could not be detected. For example, a review with only one sentence like
“It was good!” might lead to a high sentiment_score, but an
individual opinion (see below) will not be present.
Individual Opinions
An opinion is a semantic entity which contains the writer’s sentiment towards one or more subratings (topic key). A sentence can have multiple opinions. Understand that subratings are more like tags than categories. “The bed was cozy” might count as a positive opinion for both the “bed” and also the “sleeping comfort”. Certain words and expressions can increase the strength of an opinion.
Fields for each opinion:
| Field | Data Types | Description |
|---|---|---|
| polarity | Integer | Polarity of the opinion |
| strength | String | A number equal or greater to 1 for the strength fo the polarity |
| ratings | Object | A tree of ratings and their related topics found in the sentiment sentence |
| topics | Array | [DEPRECATED] A list of topics the opinion is about |
| labels | Array | [DEPRECATED] The labels for each of the topics above |
Example Output
{
"data": {
"name": "Hotel Olery",
"rating": 84.3995754408883,
"review_count": 6124,
"updated_at": "2018-08-16T11:06:06.479+00:00",
"ratings": [
{
"count": 3421,
"review_count": 3311,
"value": 85.6281788950599,
"title": "Room",
"topic": "room"
},
{
"count": 6,
"review_count": 6,
"value": 81.6666666666667,
"title": "Ambiance",
"topic": "ambiance"
}
],
"mentions": [
{
"positive_opinions": 1697,
"negative_opinions": 288,
"review_count": 1066,
"opinions_count": 1985,
"sentiment_score": 0.854911838790932,
"label": "Room",
"topic": "room"
},
{
"positive_opinions": 1649,
"negative_opinions": 127,
"review_count": 823,
"opinions_count": 1776,
"sentiment_score": 0.928490990990991,
"label": "Food & Beverages",
"topic": "fnb"
}
],
"guests": {
"countries": [
{
"country": "GB",
"label": "United Kingdom",
"ratings": [
{
"count": 799,
"review_count": 799,
"value": 85.6745932415519,
"title": "Overall",
"topic": "overall"
},
{
"count": 440,
"review_count": 440,
"value": 88.9772727272727,
"title": "Service",
"topic": "service"
}
]
}
],
"compositions": [
{
"travel_composition": "couples",
"label": "Couples",
"ratings": [
{
"count": 483,
"review_count": 483,
"value": 84.5072463768116,
"title": "Overall",
"topic": "overall"
}
]
}
]
},
"summaries": [
{
"any topic 1": {
"rating": 84.3995754408883,
"review_count": 6124,
"sentiment": "positive",
"topic": [
"overall"
],
"language": "en",
"text": "amazing hotel"
}
},
{
"any topic 3": {
"rating": 87.4388753056235,
"review_count": 3272,
"sentiment": "positive",
"topic": [
"cleanliness"
],
"language": "en",
"text": "very clean and tidy"
}
}
],
"nearby_attractions": [
{
"id": 4673267,
"name": "De Plantage",
"distance": 1.21270180267715,
"rating": 80.6451612903226,
"review_count": 31
},
{
"id": 4511559,
"name": "De Gooyer Windmill",
"distance": 1.27416427244427,
"rating": 81.6949152542373,
"review_count": 59
}
],
"recent_reviews": [
{
"title": "Pleasant and enjoyable. Please thank your excellent reception staff.",
"ratings": [
{
"title": "Room - Comfort",
"topic": "comfort",
"rating": 100,
"category": "room"
},
{
"title": "Cleanliness - General",
"topic": "cleanliness_general",
"rating": 100,
"category": "cleanliness"
},
{
"title": "Facilities - General",
"topic": "facilities_general",
"rating": 75,
"category": "facilities"
},
{
"title": "Food - Breakfast",
"topic": "breakfast",
"rating": 50,
"category": "food"
},
{
"title": "Location - General",
"topic": "location_general",
"rating": 50,
"category": "location"
},
{
"title": "Service - Staff",
"topic": "staff",
"rating": 100,
"category": "service"
},
{
"title": "Value - General",
"topic": "value_general",
"rating": 75,
"category": "value"
},
{
"title": "Overall - General",
"topic": "overall_general",
"rating": 83,
"category": "overall"
}
],
"opinions": [
{
"labels": [
"Food & Beverages",
"Food"
],
"topics": [
"fnb",
"food"
],
"polarity": "positive",
"strength": 1
},
{
"labels": [
"Food & Beverages",
"Food"
],
"topics": [
"fnb",
"food"
],
"polarity": "positive",
"strength": 1
},
{
"labels": [
"Bathroom",
"Shower"
],
"topics": [
"bathroom",
"shower"
],
"polarity": "positive",
"strength": 2
},
{
"labels": [
"Bathroom",
"Shower",
"Cleanliness",
"Stains"
],
"topics": [
"bathroom",
"shower",
"cleanliness",
"stains"
],
"polarity": "positive",
"strength": 2
},
{
"labels": [
"Room",
"Bed"
],
"topics": [
"room",
"bed"
],
"polarity": "positive",
"strength": 3
},
{
"labels": [
"Staff"
],
"topics": [
"staff"
],
"polarity": "positive",
"strength": 5
},
{
"labels": [
"Food & Beverages",
"Food"
],
"topics": [
"fnb",
"food"
],
"polarity": "positive",
"strength": 1
},
{
"labels": [
"Food & Beverages",
"Food",
"Breakfast Area"
],
"topics": [
"fnb",
"food",
"breakfast_area"
],
"polarity": "positive",
"strength": 1
},
{
"labels": [
"Staff"
],
"topics": [
"staff"
],
"polarity": "positive",
"strength": 1
},
{
"labels": [
"Beverages",
"Food & Beverages"
],
"topics": [
"beverages",
"fnb"
],
"polarity": "positive",
"strength": 1
},
{
"labels": [
"Beverages",
"Food & Beverages"
],
"topics": [
"beverages",
"fnb"
],
"polarity": "positive",
"strength": 1
}
],
"review_date": "2019-09-14",
"country_code": "GB",
"country_name": "United Kingdom",
"travel_composition": null
}
]
}
}
Parameters
| Parameter | Parameter Type | Data Types | Required | Description |
|---|---|---|---|---|
| id | path | Integer | true | ID of the company |
Time Period
By default the output will contain data from reviews published in the past 365 days.
Response Statuses
| Status Code | Reason |
|---|---|
| 200 | OK |
| 404 | The specified company was not found. |
| 403 | Client does not have access to the company. |