[GET] Sentiment

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
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

Olery Developer Portal

Review Analytics