Olery Developer Portal logo Olery Developer Portal

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

Returns aggregated data and content to fill the review widget.

Output Format

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
id Integer ID of the property
name String Name of the property
rating Float Average overall rating
review_count Integer Total number of reviews considered
updated_at String Datetime the cache was updated
ratings Hash Rating categories and their subratings
mentions Hash Sentiment opinions
guests Hash Ratings grouped by the reviewer’s travel composition and country of origin
summaries Hash Review summaries
nearby_attractions Hash Relevant nearby attractions
nearby_restaurants Hash Relevant nearby restaurants
recent_reviews Hash Recent reviews with opinions and reviewer’s country of origin
reviews_over_time Hash Review count over month and week periods
events Hash Covid number of cases over time and per country
shifts Hash Per week or per month review count difference per reviewer’s travel composition or country of origin

Ratings

The “ratings” field is an array with all rating categories.

Values for the ratings are integers with a scale of 0 to 100. Rating topics without values are not included in the object.

count Integer Count of ratings
review_count Integer Count of reviews the ratings came from
value Float Average rating
topic String Rating category

Thev1-backupre can be multiple ratings for the same topic. For this reason the count and rating_count can differ.

Guests

These ratings are structured as above with the exception that they are grouped by country and travel composition.

Mentions

A review can contain multiple mentions, even of the same topic. Also, we give an overall topic which is a compilation of the opinions per 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).

rating hash Topic of the rating (category of topics - When available)
rating[].key String key of the rating
rating[].label String label of the rating
positive_opinions Integer Count of positive opinions about the topic
negative_opinions Integer Count of negative opinions about the topic
sentiment_score Float Score taking all opinions into account
positive_percentage Float Simple percentage of positive opinions
opinions-count Integer Count of all opinions
review-count Integer Count of reviews the opinions were extracted from
topic String Sentiment subrating (see page “Sentiment Ratings”).

Summaries

The summaries consist of an array of statements. The text fields contains the content of the statement.

Nearby Attractions

It is an array of popular attractions and points of interest nearby the property.

id Integer ID of the attraction
name String English name
distance Float Direct distance in km
rating Float Average overall rating of the attraction
review_count Integer Count of reviews in the time period

Recent reviews

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
review_date Date Date on which the review was published (as stated by the source)
ratings Array Array containing the review ratings
opinions Array Opinions analysed from the review title and comments
sentiment String Overall review sentiment
country_code String Country code of the reviewer
country_name String Country name of the reviewer
travel_composition String Travel composition (friends, family, etc)

Ratings

The ratings field is an array with objects for each subrating. The rating itself is an integer on a scale of 0 to 100. All ratings on different scales are normalized into this scale. The “overall” is the main rating almost all reviews should have. Ratings without values are not included in the array.

Each subrating is in 1 out of 9 categories. Understand these categories as a suggestion by Olery. You can aggregate the ratings for the categories to make the number of rating topics more manageable for the user.

Fields for each subrating:

Field Data Types Description
title String Human-friendly title of the rating
topic String Machine name of the rating
rating Integer Rating value
category String Suggested category of the rating

Sentiment

All reviews with written content in the following languages get analyzed for the reviewer’s sentiment:

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

Method Path
GET https://agora.olery.com/v3/lexicons/languages

This analysis happens after the review was captured. The review is immmediatley available in the Review Feed and then gets updated with the sentiment data. This can take a few minutes up to several hours.

Aggregated Sentiment

The sentiment field contains the overall detected sentiment of a review. This can be any of the following values:

This field is left empty if no sentiment could be detected.

The sentiment_score field contains a score indicating the sentiment value on a scale from -1 to 1. A score of -1 means a review is 100% negative, a score of 1 means a review is 100% positive. A review with a score between 0.0 and 0.5 is considered to be neutral.

sentiment_score is also considering sentiment for which an opinion topic could not be detected. For example, a review with only one sentence like “It was good!” might lead to a high sentiment_score, but an individual opinion (see below) will not be present.

Individual Opinions

An opinion is a semantic entity which contains the writer’s sentiment towards one or more subratings (topic key). A sentence can have multiple opinions. Understand that subratings are more like tags than categories. “The bed was cozy” might count as a positive opinion for both the “bed” and also the “sleeping comfort”. Certain words and expressions can increase the strength of an opinion.

Fields for each opinion:

Field Data Types Description
polarity Integer Polarity of the opinion
strength String A number equal or greater to 1 for the strength fo the polarity
ratings Object A tree of ratings and their related topics found in the sentiment sentence
topics Array [DEPRECATED] A list of topics the opinion is about
labels Array [DEPRECATED] The labels for each of the topics above

Example Output

    {
      "data": {
        "name": "Hotel Olery",
        "rating": 84.3995754408883,
        "review_count": 6124,
        "updated_at": "2018-08-16T11:06:06.479+00:00",
        "ratings": [
          {
            "count": 3421,
            "review_count": 3311,
            "value": 85.6281788950599,
            "title": "Room",
            "topic": "room"
          },
          {
            "count": 6,
            "review_count": 6,
            "value": 81.6666666666667,
            "title": "Ambiance",
            "topic": "ambiance"
          }
        ],
        "mentions": [
          {
            "positive_opinions": 1697,
            "negative_opinions": 288,
            "review_count": 1066,
            "opinions_count": 1985,
            "sentiment_score": 0.854911838790932,
            "label": "Room",
            "topic": "room"
          },
          {
            "positive_opinions": 1649,
            "negative_opinions": 127,
            "review_count": 823,
            "opinions_count": 1776,
            "sentiment_score": 0.928490990990991,
            "label": "Food & Beverages",
            "topic": "fnb"
          }
        ],
        "guests": {
          "countries": [
            {
              "country": "GB",
              "label": "United Kingdom",
              "ratings": [
                {
                  "count": 799,
                  "review_count": 799,
                  "value": 85.6745932415519,
                  "title": "Overall",
                  "topic": "overall"
                },
                {
                  "count": 440,
                  "review_count": 440,
                  "value": 88.9772727272727,
                  "title": "Service",
                  "topic": "service"
                }
              ]
            }
          ],
          "compositions": [
            {
              "travel_composition": "couples",
              "label": "Couples",
              "ratings": [
                {
                  "count": 483,
                  "review_count": 483,
                  "value": 84.5072463768116,
                  "title": "Overall",
                  "topic": "overall"
                }
              ]
            }
          ]
        },
        "summaries": [
          {
            "any topic 1": {
              "rating": 84.3995754408883,
              "review_count": 6124,
              "sentiment": "positive",
              "topic": [
                "overall"
              ],
              "language": "en",
              "text": "amazing hotel"
            }
          },
          {
            "any topic 3": {
              "rating": 87.4388753056235,
              "review_count": 3272,
              "sentiment": "positive",
              "topic": [
                "cleanliness"
              ],
              "language": "en",
              "text": "very clean and tidy"
            }
          }
        ],
        "nearby_attractions": [
          {
            "id": 4673267,
            "name": "De Plantage",
            "distance": 1.21270180267715,
            "rating": 80.6451612903226,
            "review_count": 31
          },
          {
            "id": 4511559,
            "name": "De Gooyer Windmill",
            "distance": 1.27416427244427,
            "rating": 81.6949152542373,
            "review_count": 59
          }
        ],
        "recent_reviews": [
          {
            "title": "Pleasant and enjoyable. Please thank your excellent reception staff.",
            "ratings": [
              {
                "title": "Room - Comfort",
                "topic": "comfort",
                "rating": 100,
                "category": "room"
              },
              {
                "title": "Cleanliness - General",
                "topic": "cleanliness_general",
                "rating": 100,
                "category": "cleanliness"
              },
              {
                "title": "Facilities - General",
                "topic": "facilities_general",
                "rating": 75,
                "category": "facilities"
              },
              {
                "title": "Food - Breakfast",
                "topic": "breakfast",
                "rating": 50,
                "category": "food"
              },
              {
                "title": "Location - General",
                "topic": "location_general",
                "rating": 50,
                "category": "location"
              },
              {
                "title": "Service - Staff",
                "topic": "staff",
                "rating": 100,
                "category": "service"
              },
              {
                "title": "Value - General",
                "topic": "value_general",
                "rating": 75,
                "category": "value"
              },
              {
                "title": "Overall - General",
                "topic": "overall_general",
                "rating": 83,
                "category": "overall"
              }
            ],
            "opinions": [
              {
                "labels": [
                  "Food & Beverages",
                  "Food"
                ],
                "topics": [
                  "fnb",
                  "food"
                ],
                "polarity": "positive",
                "strength": 1
              },
              {
                "labels": [
                  "Food & Beverages",
                  "Food"
                ],
                "topics": [
                  "fnb",
                  "food"
                ],
                "polarity": "positive",
                "strength": 1
              },
              {
                "labels": [
                  "Bathroom",
                  "Shower"
                ],
                "topics": [
                  "bathroom",
                  "shower"
                ],
                "polarity": "positive",
                "strength": 2
              },
              {
                "labels": [
                  "Bathroom",
                  "Shower",
                  "Cleanliness",
                  "Stains"
                ],
                "topics": [
                  "bathroom",
                  "shower",
                  "cleanliness",
                  "stains"
                ],
                "polarity": "positive",
                "strength": 2
              },
              {
                "labels": [
                  "Room",
                  "Bed"
                ],
                "topics": [
                  "room",
                  "bed"
                ],
                "polarity": "positive",
                "strength": 3
              },
              {
                "labels": [
                  "Staff"
                ],
                "topics": [
                  "staff"
                ],
                "polarity": "positive",
                "strength": 5
              },
              {
                "labels": [
                  "Food & Beverages",
                  "Food"
                ],
                "topics": [
                  "fnb",
                  "food"
                ],
                "polarity": "positive",
                "strength": 1
              },
              {
                "labels": [
                  "Food & Beverages",
                  "Food",
                  "Breakfast Area"
                ],
                "topics": [
                  "fnb",
                  "food",
                  "breakfast_area"
                ],
                "polarity": "positive",
                "strength": 1
              },
              {
                "labels": [
                  "Staff"
                ],
                "topics": [
                  "staff"
                ],
                "polarity": "positive",
                "strength": 1
              },
              {
                "labels": [
                  "Beverages",
                  "Food & Beverages"
                ],
                "topics": [
                  "beverages",
                  "fnb"
                ],
                "polarity": "positive",
                "strength": 1
              },
              {
                "labels": [
                  "Beverages",
                  "Food & Beverages"
                ],
                "topics": [
                  "beverages",
                  "fnb"
                ],
                "polarity": "positive",
                "strength": 1
              }
            ],
            "review_date": "2019-09-14",
            "country_code": "GB",
            "country_name": "United Kingdom",
            "travel_composition": null
          }
        ]
      }
    }

Parameters

Parameter Parameter Type Data Types Required Description
id path Integer true ID of the company

Time Period

By default the output will contain data from reviews published in the past 365 days.

Response Statuses

Status Code Reason
200 OK
404 The specified company was not found.
403 Client does not have access to the company.