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 content in English, German, French, Dutch, Italian and Spanish get analyzed for the reviewer’s sentiment towards certain topics (see page “Sentiment Topics”).

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

You are limited to 1 request per second. Please use this endpoint responsibly. Requests with long time periods and multiple groupings are resource-intensive.

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
topic String Topic 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
review_count Integer Count of reviews the opinions are from
opinions_count Integer Total count of opinions
sentiment_score Float Sentiment on a scale from -1 to 1
date Date Start date of each time period, if per parameter is used
segment String Segment, if segment parameter is used

In case of grouping by per or segment the data is found in the opinions object for each group.

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/opinions?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":[  
      {  
         "topic":"room",
         "title":"Room",
         "label":"Room",
         "positive_opinions":83,
         "negative_opinions":12,
         "review_count":60,
         "opinions_count":95,
         "sentiment_score":0.8736842105263158
      },
      {  
         "topic":"location",
         "title":"Location",
         "label":"Location",
         "positive_opinions":65,
         "negative_opinions":3,
         "review_count":48,
         "opinions_count":68,
         "sentiment_score":0.9558823529411765
      },
      {  
         "topic":"staff",
         "title":"Staff",
         "label":"Staff",
         "positive_opinions":57,
         "negative_opinions":5,
         "review_count":50,
         "opinions_count":62,
         "sentiment_score":0.9193548387096774
      },
   ]
}

Response Statuses

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