| Method | Path |
|---|---|
GET |
https://agora.olery.com/v3/destination/:country_code/sentiment |
Returns per sentiment topic (subrating) counts of positive, negative, neutral opinions and reviews along with the score and the positive opinions percentage (as time series and/or grouped by traveler segment)
Output Format
The meta field contains general information about the API call.
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 |
|---|---|---|
| date | Date | Start date of each time period, if per parameter is used |
| segment | String | Segment, if segment parameter is used |
| subsegment | String | Segment, if subsegment parameter is used |
| rating | Hash | Topic of the rating (category of the subrating - When available) |
| rating[].key | String | key of the rating |
| rating[].label | String | label of the rating |
| positive_opinions | Integer | Count of times the topic was mentioned in a positive context |
| negative_opinions | Integer | Count of times the topic was mentioned in a negative context |
| neutral_opinions | Integer | Count of times the topic was mentioned in a neutral context |
| opinions_count | Integer | Total count of opinions |
| review_count | Integer | Count of reviews the opinions are from |
| sentiment_score | Float | Sentiment Score on a scale from 0 to 10 |
| positive_percentage | Float | Simple percentage of positive opinions |
The data is found in the sentiment object for each group.
Parameters
| Parameter | Parameter Type | Data Types | Required | Description |
|---|---|---|---|---|
| country_code | path | Integer | true | ISO alpha-2 country code |
| start_date | query | Date | true | Start date in ISO 8601 format |
| end_date | query | Date | true | End date in ISO 8601 format |
| per | query | String | false | Date grouping (day, week, month, quarter, year) |
| segment | query | String | false | Segment grouping (origin-country, composition, language and hotel fields, see below) |
| subsegment | query | String | false | Subsegment grouping (origin-country, composition, language and hotel fields, see below) |
| topics | query | String | false | Filter the output by list of comma-separated rating categories |
| sources | query | Array | false | Filter the data by list of comma-separated sources names |
| countries | query | Array | false | Filter the data by list of comma-separated countries codes |
| languages | query | Array | false | Filter the data by list of comma-separated languages codes |
| compositions | query | Array | false | Filter the data by list of comma-separated compositions codes |
| exclude_sources | query | Array | false | Filter out the data by list of comma-separated sources names |
| exclude_countries | query | Array | false | Filter out the data by list of comma-separated countries codes |
| exclude_languages | query | Array | false | Filter out the data by list of comma-separated languages codes |
| exclude_compositions | query | Array | false | Filter out the data by list of comma-separated compositions codes |
Segmentation
There are 3 segmentation possible. The first is a time series data grouping specified by the per parameter, which accepts the following values:
dayweekmonthquarteryear
For the subsegment and the subsegment, review data or property fields can be used for per group analysis. Review data fields include:
origin-country: origin of the reviewercomposition: travel composition of the reviewerlanguage: language of review text (title and comments)
Property fields are listed below
property_typestarscountyregionprovincestatenation
Example Call
https://agora.olery.com/v3/destination/NL/sentiment?start_date=2020-01-01&end_date=2021-12-31&segment=composition&auth_token=XXX
Example Output
{
"meta": {
"per": null,
"segment": "travel_composition",
"subsegment": null
},
"data": [
{
"date": null,
"segment": "Friends",
"subsegment": null,
"sentiment": [
{
"rating": {
"key": "overall",
"label": "Overall"
},
"topic": "overall",
"label": "Overall",
"positive_opinions": 1287,
"negative_opinions": 251,
"neutral_opinions": 393,
"opinions_count": 1931,
"review_count": 265,
"sentiment_score": 9.024864024864025,
"positive_percentage": 83.68010403120937
},
{
"rating": {
"key": "service",
"label": "Service"
},
"topic": "personnel",
"label": "Personnel",
"positive_opinions": 147,
"negative_opinions": 28,
"neutral_opinions": 52,
"opinions_count": 227,
"review_count": 164,
"sentiment_score": 9.047619047619047,
"positive_percentage": 84.0
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "sports_facilties",
"label": "Sports Facilties",
"positive_opinions": 26,
"negative_opinions": 9,
"neutral_opinions": 15,
"opinions_count": 50,
"review_count": 37,
"sentiment_score": 8.26923076923077,
"positive_percentage": 74.28571428571429
},
{
"rating": {
"key": "fnb",
"label": "Food & Beverages"
},
"topic": "drink",
"label": "Drink",
"positive_opinions": 32,
"negative_opinions": 11,
"neutral_opinions": 26,
"opinions_count": 69,
"review_count": 55,
"sentiment_score": 8.28125,
"positive_percentage": 74.4186046511628
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "attraction",
"label": "Attraction",
"positive_opinions": 30,
"negative_opinions": 2,
"neutral_opinions": 7,
"opinions_count": 39,
"review_count": 22,
"sentiment_score": 9.666666666666668,
"positive_percentage": 93.75
},
{
"rating": {
"key": "location",
"label": "Location"
},
"topic": "surrounding_area",
"label": "Surrounding Area",
"positive_opinions": 18,
"negative_opinions": 5,
"neutral_opinions": 29,
"opinions_count": 52,
"review_count": 48,
"sentiment_score": 8.61111111111111,
"positive_percentage": 78.26086956521739
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "room",
"label": "Room",
"positive_opinions": 82,
"negative_opinions": 24,
"neutral_opinions": 32,
"opinions_count": 138,
"review_count": 84,
"sentiment_score": 8.536585365853657,
"positive_percentage": 77.35849056603773
},
{
"rating": {
"key": "cleanliness",
"label": "Cleanliness"
},
"topic": "hygiene",
"label": "Hygiene",
"positive_opinions": 42,
"negative_opinions": 15,
"neutral_opinions": 7,
"opinions_count": 64,
"review_count": 52,
"sentiment_score": 8.214285714285715,
"positive_percentage": 73.6842105263158
},
{
"rating": {
"key": "cleanliness",
"label": "Cleanliness"
},
"topic": "housekeeping",
"label": "Housekeeping",
"positive_opinions": 33,
"negative_opinions": 5,
"neutral_opinions": 11,
"opinions_count": 49,
"review_count": 45,
"sentiment_score": 9.242424242424242,
"positive_percentage": 86.84210526315789
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "bar",
"label": "Bar",
"positive_opinions": 27,
"negative_opinions": 6,
"neutral_opinions": 32,
"opinions_count": 65,
"review_count": 55,
"sentiment_score": 8.88888888888889,
"positive_percentage": 81.81818181818181
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "bathroom",
"label": "Bathroom",
"positive_opinions": 28,
"negative_opinions": 11,
"neutral_opinions": 8,
"opinions_count": 47,
"review_count": 26,
"sentiment_score": 8.035714285714285,
"positive_percentage": 71.7948717948718
},
{
"rating": {
"key": "fnb",
"label": "Food & Beverages"
},
"topic": "breakfast",
"label": "Breakfast",
"positive_opinions": 6,
"negative_opinions": 3,
"neutral_opinions": 8,
"opinions_count": 17,
"review_count": 14,
"sentiment_score": 7.5,
"positive_percentage": 66.66666666666667
},
{
"rating": {
"key": "value",
"label": "Value"
},
"topic": "entertainment_value",
"label": "Entertainment Value",
"positive_opinions": 6,
"negative_opinions": 12,
"neutral_opinions": 4,
"opinions_count": 22,
"review_count": 16,
"sentiment_score": 2.5,
"positive_percentage": 33.333333333333336
},
{
"rating": {
"key": "service",
"label": "Service"
},
"topic": "reception",
"label": "Reception",
"positive_opinions": 4,
"negative_opinions": 7,
"neutral_opinions": 4,
"opinions_count": 15,
"review_count": 10,
"sentiment_score": 2.857142857142857,
"positive_percentage": 36.36363636363637
},
{
"rating": {
"key": "service",
"label": "Service"
},
"topic": "checkin",
"label": "Checkin",
"positive_opinions": 0,
"negative_opinions": 1,
"neutral_opinions": 7,
"opinions_count": 8,
"review_count": 8,
"sentiment_score": 0.0,
"positive_percentage": 0.0
},
{
"rating": {
"key": "service",
"label": "Service"
},
"topic": "checkout",
"label": "Checkout",
"positive_opinions": 0,
"negative_opinions": 0,
"neutral_opinions": 1,
"opinions_count": 1,
"review_count": 1,
"sentiment_score": 5.0,
"positive_percentage": null
},
{
"rating": {
"key": "service",
"label": "Service"
},
"topic": "ticket_office",
"label": "Ticket Office",
"positive_opinions": 0,
"negative_opinions": 0,
"neutral_opinions": 4,
"opinions_count": 4,
"review_count": 4,
"sentiment_score": 5.0,
"positive_percentage": null
},
{
"rating": {
"key": "cleanliness",
"label": "Cleanliness"
},
"topic": "humidity",
"label": "Humidity",
"positive_opinions": 0,
"negative_opinions": 1,
"neutral_opinions": 0,
"opinions_count": 1,
"review_count": 1,
"sentiment_score": 0.0,
"positive_percentage": 0.0
},
{
"rating": {
"key": "fnb",
"label": "Food & Beverages"
},
"topic": "food",
"label": "Food",
"positive_opinions": 215,
"negative_opinions": 20,
"neutral_opinions": 19,
"opinions_count": 254,
"review_count": 148,
"sentiment_score": 9.534883720930232,
"positive_percentage": 91.48936170212765
},
{
"rating": {
"key": "value",
"label": "Value"
},
"topic": "value_for_money",
"label": "Value for money",
"positive_opinions": 106,
"negative_opinions": 19,
"neutral_opinions": 20,
"opinions_count": 145,
"review_count": 103,
"sentiment_score": 9.10377358490566,
"positive_percentage": 84.8
},
{
"rating": {
"key": "location",
"label": "Location"
},
"topic": "transport",
"label": "Transport",
"positive_opinions": 29,
"negative_opinions": 17,
"neutral_opinions": 31,
"opinions_count": 77,
"review_count": 60,
"sentiment_score": 7.068965517241379,
"positive_percentage": 63.04347826086956
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "spa",
"label": "Spa",
"positive_opinions": 9,
"negative_opinions": 1,
"neutral_opinions": 6,
"opinions_count": 16,
"review_count": 14,
"sentiment_score": 9.444444444444445,
"positive_percentage": 90.0
},
{
"rating": {
"key": "ambience",
"label": "Ambience"
},
"topic": "sound",
"label": "Sound",
"positive_opinions": 9,
"negative_opinions": 2,
"neutral_opinions": 6,
"opinions_count": 17,
"review_count": 14,
"sentiment_score": 8.88888888888889,
"positive_percentage": 81.81818181818181
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "internet",
"label": "Internet",
"positive_opinions": 1,
"negative_opinions": 2,
"neutral_opinions": 5,
"opinions_count": 8,
"review_count": 7,
"sentiment_score": 2.5,
"positive_percentage": 33.333333333333336
},
{
"rating": {
"key": "service",
"label": "Service"
},
"topic": "entertainers",
"label": "Entertainers",
"positive_opinions": 1,
"negative_opinions": 0,
"neutral_opinions": 2,
"opinions_count": 3,
"review_count": 3,
"sentiment_score": 10.0,
"positive_percentage": 100.0
},
{
"rating": {
"key": "ambience",
"label": "Ambience"
},
"topic": "decor",
"label": "Decor",
"positive_opinions": 1,
"negative_opinions": 1,
"neutral_opinions": 0,
"opinions_count": 2,
"review_count": 2,
"sentiment_score": 5.0,
"positive_percentage": 50.0
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "orders",
"label": "Orders",
"positive_opinions": 0,
"negative_opinions": 0,
"neutral_opinions": 1,
"opinions_count": 1,
"review_count": 1,
"sentiment_score": 5.0,
"positive_percentage": null
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "restaurant",
"label": "Restaurant",
"positive_opinions": 201,
"negative_opinions": 21,
"neutral_opinions": 17,
"opinions_count": 239,
"review_count": 137,
"sentiment_score": 9.477611940298509,
"positive_percentage": 90.54054054054055
},
{
"rating": {
"key": "ambience",
"label": "Ambience"
},
"topic": "atmosphere",
"label": "Atmosphere",
"positive_opinions": 10,
"negative_opinions": 1,
"neutral_opinions": 0,
"opinions_count": 11,
"review_count": 11,
"sentiment_score": 9.5,
"positive_percentage": 90.9090909090909
},
{
"rating": {
"key": "ambience",
"label": "Ambience"
},
"topic": "light",
"label": "Light",
"positive_opinions": 2,
"negative_opinions": 0,
"neutral_opinions": 1,
"opinions_count": 3,
"review_count": 3,
"sentiment_score": 10.0,
"positive_percentage": 100.0
},
{
"rating": {
"key": "cleanliness",
"label": "Cleanliness"
},
"topic": "odor",
"label": "Odor",
"positive_opinions": 3,
"negative_opinions": 3,
"neutral_opinions": 0,
"opinions_count": 6,
"review_count": 5,
"sentiment_score": 5.0,
"positive_percentage": 50.0
},
{
"rating": {
"key": "facilities",
"label": "Facilities"
},
"topic": "entertainment",
"label": "Entertainment Facilities",
"positive_opinions": 2,
"negative_opinions": 0,
"neutral_opinions": 0,
"opinions_count": 2,
"review_count": 1,
"sentiment_score": 10.0,
"positive_percentage": 100.0
}
]
}
]
}
Response Statuses
| Status Code | Reason |
|---|---|
| 200 | OK |
| 404 | Company not found |
| 403 | No access, no authentication token |
| 400 | Missing or incorrect dates |