Olery Developer Portal logo Olery Developer Portal

Method Path
GET https://agora.olery.com/v3/companies/:id/sentiment

Returns sentiment opinions stats (as times series and/or grouped by traveler segment)

About Sentiment

All reviews with written comment in our list of supported languages get analyzed for the reviewer’s sentiment towards certain subratings (see page “Sentiment Ratings”).

For an updated list of supported languages, call the following endpoint:

Method Path
GET https://agora.olery.com/v3/lexicons/languages?auth_token=TOKEN

Each review can contain multiple opinions for the same or different subratings. “The room was nice. It was also very large.” might count as 2 positive opinions for “room”.

Output Format

The meta field contains general information about the property.

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
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
topic String Subrating of the rating
title String Humanized form of the topic (subrating)
label String Humanized form of the topic (subrating)
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 on a scale from 0 to 10
positive_percentage Float Simple percentage of positive opinions

In case of grouping by per or segment the data is found in the opinions object for each group. We also add an overall subrating aggregating data from the other subratings in the same 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).

Parameters

Parameter Parameter Type Data Types Required Description
id path Integer true ID of the company
start_date query Date true Start date in ISO 8601 format
end_date query Date true End date in ISO 8601 format
subratings query Boolean false Toggle subratings array
per query String false Date grouping (day, month, quarter, year)
segment query String false Segment grouping (origin-country, composition, language, source)
topic query String false Filter the output by a list of comma-separated topics

Example Call

https://agora.olery.com/v3/companies/38/sentiment?start_date=2018-01-01&end_date=2018-03-31&per=month&segment=composition&auth_token=XXX

Example Output

{  
   "meta":{  
      "company":{  
         "id":38,
         "name":"Hotel Casa"
      }
   },
   "data":[  
       {
         "rating": null,
         "topic": "overall",
         "title": "Overall",
         "label": "Overall",
         "positive_opinions": 148,
         "negative_opinions": 20,
         "neutral_opinions": 70,
         "opinions_count": 225,
         "review_count": 158,
         "sentiment_score": 8.75,
         "positive_percentage": 0.8,
      },
      { 
         "rating": {
            "key": "service",
            "label": "Service"
         },
         "topic":"room",
         "title":"Room",
         "label":"Room",
         "positive_opinions":83,
         "negative_opinions":12,
         "neutral_opinions": 11,
         "review_count":60,
         "opinions_count":95,
         "sentiment_score":8.3
      },
      {  
         "rating": null,
         "topic":"location",
         "title":"Location",
         "label":"Location",
         "positive_opinions":65,
         "negative_opinions":3,
         "neutral_opinions": 17,
         "review_count":48,
         "opinions_count":68,
         "sentiment_score":9
      },
      {
         "rating": {
           "key": "service",
           "label": "Service"
         },
         "topic":"staff",
         "title":"Staff",
         "label":"Staff",
         "positive_opinions":57,
         "negative_opinions":5,
         "neutral_opinions": 42,
         "review_count":50,
         "opinions_count":62,
         "sentiment_score":7.7
      },
   ]
}

Response Statuses

Status Code Reason
200 OK
404 Company not found
403 No access, no authentication token
400 Missing or incorrect dates