| Method | Path |
|---|---|
GET |
https://agora.olery.com/v3/companies/:id/review_content |
Returns ratings and other content, aggregated from all avaialble review for one property.
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 |
|---|---|---|
| name | String | Name of the property |
| gei | Float | Current Guest Experience Index value |
| review-count | Integer | Total number of reviews |
| opinions | Hash | Count of opinions and sentiment score per topic |
| ratings | Hash | Rating categories and their subratings |
| country-ratings | Hash | Ratings split by the reviewer’s country of origin |
| composition-ratings | Hash | Ratings split by the reviewer’s travel composition |
Ratings
The “ratings” field is an nested object with the rating categories (e.g. “room” or “overall”) and subratings (e.g. “bed”). The categories are an average of the subratings. The data is aggregated from all available reviews in the selected time period.
Values for the ratings are integers with a scale of 0 to 100. Rating topics without values are not included in the object.
There can be multiple ratings for the same topic. For this reason the ratings-count and review-count can differ.
Country & Composition Ratings
These ratings are struced as above with the execption that they split by country and travel composition.
Opinions
A review can contain mutliple opinions, even of the same subrating. We identify the subratings and the their related opinions. Also, we give an overall subrating 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).
| positive_opinions | Integer | Count of positive opinions about the subrating |
| negative_opinions | Integer | Count of negative opinions about the subrating |
| 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 |
Example Request
https://agora.olery.com/v3/companies/123/review_content?auth_token=abc123&content=ratings,country_ratings,composition_ratings,opinions
Example Output
{
"data": {
"company_id": 123,
"name": "Hotel Olery",
"review_count": 698,
"gei": 81.2220972483482,
"ratings": {
"overall": {
"count": 796,
"review_count": 698,
"subratings": {
"condition": {
"count": 70,
"review_count": 70,
"title": "Condition",
"value": 79.7142857142857
},
"overall_general": {
"count": 726,
"review_count": 698,
"title": "General",
"value": 78.504132231405
}
},
"title": "Overall",
"value": 78.6105527638191
},
"ambiance": {
"count": 25,
"review_count": 25,
"subratings": {
"ambiance_general": {
"count": 25,
"review_count": 25,
"title": "General",
"value": 73.6
}
},
"title": "Ambiance",
"value": 73.6
}
},
"composition_ratings": {
"couples": {
"overall": {
"count": 301,
"review_count": 278,
"subratings": {
"overall_general": {
"count": 301,
"review_count": 278,
"title": "General",
"value": 76.9169435215947
}
},
"title": "Overall",
"value": 76.9169435215947
}
}
},
"country_ratings": {
"US": {
"overall": {
"count": 2,
"review_count": 2,
"subratings": {
"overall_general": {
"count": 2,
"review_count": 2,
"title": "General",
"value": 81.5
}
},
"title": "Overall",
"value": 81.5
},
"cleanliness": {
"count": 2,
"review_count": 2,
"subratings": {
"cleanliness_general": {
"count": 2,
"review_count": 2,
"title": "General",
"value": 90
}
},
"title": "Cleanliness",
"value": 90
}
}
},
"opinions": {
"overall": {
"rating": null,
"topic": "overall",
"title": "Overall",
"label": "Overall",
"opinions_count": 1963,
"review_count": 1626,
"sentiment_score": 9.183035714285715,
"positive_percentage": 0.8595548733691482,
"positive_opinions": 1120,
"negative_opinions": 183,
"neutral_opinions": 660
},
"bar": {
"rating": {
"key": "facilities",
"label": "Facilities"
},
"negative_opinions": 1,
"opinions_count": 11,
"positive_opinions": 10,
"review_count": 9,
"sentiment_score": 0.9090909090909091
},
"bathroom": {
"rating": null,
"negative_opinions": 23,
"opinions_count": 46,
"positive_opinions": 23,
"review_count": 40,
"sentiment_score": 0.5
}
}
}
}
Parameters
| Parameter | Parameter Type | Data Types | Required | Description |
|---|---|---|---|---|
| id | path | Integer | true | ID of the company |
| days | query | Integer | false | Time period |
| end_date | query | Date | false | End date in ISO 8601 format |
| content | query | String | false | Content blocks to be returned |
Time Period
By default the output will contain data from reviews published in the past 365 days. By using the days parameter, a custom number of past days can be set.
Content
The output is divided into several content blocks. The content parameter selects which content blocks are returned. If no content is selected, only basic information is returned.
With a comma-separated list multiple content blocks can be selected.
Avaialble blocks:
ratingscountry_ratingscomposition_ratingsopinions
Example parameter: content:ratings,country_ratings
Response Statuses
| Status Code | Reason |
|---|---|
| 200 | OK |
| 404 | The specified company was not found. |
| 403 | Client does not have access to the company. |
Response Fields
| Field | Data Types | Description |
|---|---|---|
| data | Hash | JSON object containing aggregated review data |