[GET] Ratings

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.

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

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
sources	query	Array	false	Filter the data by list of comma-separated sources names
countries	query	Array	false	Filter the data by list of comma-separated countries codes
exclude_sources	query	Array	false	Filter out the data by list of comma-separated sources names
exclude_countries	query	Array	false	Filter out the data by list of comma-separated countries codes

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

Olery Developer Portal

Review Analytics