Olery Developer Portal logo Olery Developer Portal

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

Returns ratings and other content, aggregated from all avaialble review for one property.

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
name String Name of the property
gei Float Current Guest Experience Index value
review-count Fixnum Total number of reviews
opinions Hash Count of opinions and sentiment score per topic
ratings Hash Rating categories and their subratings
country-ratings Hash Ratings split by the reviewer’s country of origin
composition-ratings Hash Ratings split by the reviewer’s travel composition

Ratings

The “ratings” field is an nested object with the rating categories (e.g. “room” or “overall”) and subratings (e.g. “bed”). The categories are an average of the subratings. The data is aggregated from all available reviews in the selected time period.

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

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

Country & Composition Ratings

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

Opinions

A reviews can contain mutliple opinions, 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 Fixnum Count of positive opinions about the topic
negative_opinions Fixnum Count of negative opinions about the topic
sentiment_score Float Score taking all opinions into account
opinions-count Fixnum Count of all opinions
review-count Fixnum Count of reviews the opinions were extracted from

Example Output

{
    "data": {
        "company_id": 123,
        "name": "Hotel Olery",
        "review_count": 698,
        "gei": 81.2220972483482,
        "ratings": {
            "overall": {
                "count": 796,
                "review_count": 698,
                "subratings": {
                    "condition": {
                        "count": 70,
                        "review_count": 70,
                        "title": "Condition",
                        "value": 79.7142857142857
                    },
                    "overall_general": {
                        "count": 726,
                        "review_count": 698,
                        "title": "General",
                        "value": 78.504132231405
                    }
                },
                "title": "Overall",
                "value": 78.6105527638191
            },
            "ambiance": {
                "count": 25,
                "review_count": 25,
                "subratings": {
                    "ambiance_general": {
                        "count": 25,
                        "review_count": 25,
                        "title": "General",
                        "value": 73.6
                    }
                },
                "title": "Ambiance",
                "value": 73.6
            }
        },
        "composition_ratings": {
            "couples": {
                "overall": {
                    "count": 301,
                    "review_count": 278,
                    "subratings": {
                        "overall_general": {
                            "count": 301,
                            "review_count": 278,
                            "title": "General",
                            "value": 76.9169435215947
                        }
                    },
                    "title": "Overall",
                    "value": 76.9169435215947
                }
            }
        },
        "country_ratings": {
            "US": {
                "overall": {
                    "count": 2,
                    "review_count": 2,
                    "subratings": {
                        "overall_general": {
                            "count": 2,
                            "review_count": 2,
                            "title": "General",
                            "value": 81.5
                        }
                    },
                    "title": "Overall",
                    "value": 81.5
                },
                "cleanliness": {
                    "count": 2,
                    "review_count": 2,
                    "subratings": {
                        "cleanliness_general": {
                            "count": 2,
                            "review_count": 2,
                            "title": "General",
                            "value": 90
                        }
                    },
                    "title": "Cleanliness",
                    "value": 90
                }
            }
        },
        "opinions": {
            "bar": {
                "negative_opinions": 1,
                "opinions_count": 11,
                "positive_opinions": 10,
                "review_count": 9,
                "sentiment_score": 0.9090909090909091
            },
            "bathroom": {
                "negative_opinions": 23,
                "opinions_count": 46,
                "positive_opinions": 23,
                "review_count": 40,
                "sentiment_score": 0.5
            }
        }
    }
}

Parameters

Parameter Parameter Type Data Types Required Description
id path Fixnum true ID of the company
days query Fixnum false Time period
content query String false Content blocks to be returned

Time Period

By default the output will contain data from reviews published in the past 365 days. By using the days parameter, a custom number of past days can be set.

Content

The output is divided into several content blocks. The content parameter selects which content blocks are returned. If no content is selected, only basic information is returned.

With a comma-separated list multiple content blocks can be selected.

Avaialble blocks:

Example parameter: content:ratings,country-ratings

Response Statuses

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

Response Fields

Field Data Types Description
data Hash JSON object containing aggregated review data