Olery Developer Portal logo Olery Developer Portal

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)

Segmentation

There are 3 segmentation possible. The first is a time series data grouping specified by the per parameter, which accepts the following values:

For the subsegment and the subsegment, review data or property fields can be used for per group analysis. Review data fields include:

Property fields are listed below

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