| 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 |
| opinions | Hash | Count of opinions and sentiment score per topic |
| ratings | Hash | Rating categories and their subratings |
| country-ratings | Hash | Ratings grouped by the reviewer’s country of origin |
| composition-ratings | Hash | Ratings grouped by the reviewer’s travel composition |
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 |
There can be multiple ratings for the same topic. For this
reason the count and rating_count can differ.
Guests
These ratings are struced as above with the execption that they are grouped by country and travel composition.
Mentions
A reviews can contain mutliple mentions, even of the same topic.
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).
| 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 | Topic of the mentions |
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) |
| title | String | Title of the review |
| 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 English, German, French, Dutch, Italian and Spanish get analyzed for the reviewer’s sentiment.
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 topics. A sentence can have multiple opinions. Understand that topics 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 |
|---|---|---|
| topics | Array | Topics the opinion is about |
| polarity | String | Polarity of the opinion |
| strength | Integer | Strength of the opinion (can take any value) |
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. |