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
opinions Hash Count of opinions and sentiment score per topic
ratings Hash Rating categories and their subratings
country-ratings Hash Ratings grouped by the reviewer’s country of origin
composition-ratings Hash Ratings grouped by the reviewer’s travel composition

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

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

Guests

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

Mentions

A reviews can contain mutliple mentions, even of the same topic.

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

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 Topic of the mentions

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)
title String Title of the review
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 English, German, French, Dutch, Italian and Spanish get analyzed for the reviewer’s sentiment.

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 topics. A sentence can have multiple opinions. Understand that topics 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
topics Array Topics the opinion is about
polarity String Polarity of the opinion
strength Integer Strength of the opinion (can take any value)

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.