Olery Developer Portal logo Olery Developer Portal

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

Returns rating categories and subratings (as times series and/or grouped by traveler segment)

About Ratings

Each review has no, one or more than one rating. Each rating is normalized into a scale of 0-100, no matter the original scale.

All ratings are grouped into subratings by topic (see “Rating Topics” page). Additionally, we group these subratings into categories, which are simple averages of the subratings.

The “overall” is the main rating almost all reviews should have.

By default, the endpoint returns only rating categories. Ratings without values are not included in the output.

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
value Float Rating value on a scale 0-100
topic String Topic of the rating
count Integer Count of ratings, one review might have more than one rating
review_count Integer Count of reviews the ratings are from
subratings Array Subratings with the same fields as above
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 stats 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)
topics query String false Filter the output by list of comma-separated rating categories

Example Call

https://agora.olery.com/v3/companies/38/ratings?start_date=2018-01-01&end_date=2018-03-31&per=month&subratings=true&topic=overall&auth_token=XXX

Example Output

{  
   "meta":{  
      "company":{  
         "id":38,
         "name":"Hotel ABC"
      }
   },
   "data":[  
      {  
         "value":86.6117216117216,
         "topic":"room",
         "title":"Room",
         "count":273,
         "review_count":260
      },
      {  
         "value":80,
         "topic":"ambiance",
         "title":"Ambiance",
         "count":1,
         "review_count":1
      },
      {  
         "value":87.7799227799228,
         "topic":"cleanliness",
         "title":"Cleanliness",
         "count":259,
         "review_count":259
      },
      {  
         "value":85.1004273504274,
         "topic":"overall",
         "title":"Overall",
         "count":468,
         "review_count":468
      }
   ]
}

Response Statuses

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