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.

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

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

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.