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

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.