Olery Developer Portal logo Olery Developer Portal

Reputation Management

[GET] Review Feed

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

This endpoint returns individual reviews and their metadata.

We highly recommend reading the “Getting started” guide to get an idea on how an efficient implementation could look like.

Incremental Updates

By using the since parameter reviews can be imported und updated incrementally. Only reviews created or updated after the specified point in time are returned. Recommended is an 1 hour import frequency. Run an import, save the time of the request and use it to fill the since parameter the next time.

Be aware, reviews often get updated after creation. In this case the full review appears again in the output. Be prepared to handle such updates.

Filtering by Dates & Sources

By default all available reviews are returned. When specifying a start_date and end_date only reviews published (not created, see exaplanation below) within that period are returned.

You can also filter by review sources by setting a sources parameter. Use commas to separate multiple sources. Make sure to use the source names defined by Olery.

We recommend to use these parameters only for debugging or other special cases. Use the since for imports, otherwise you might miss data.

Pagination

Reviews are paginated with a default of 20 reviews per page. The fields previous_url and next_url can be used to navigate between previous/next review pages. These fields are set to NULL if no URL is available (e.g. previous_url is NULL on the first page).

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 String Storage ID of the review, preserved on review updates (use this ID in your database)
review_id String Unique ID of the review (this is generated from the review site and may change)
id_on_review_site String ID of the review on the review source (if present)
connection_url String URL of the property on the source website (we call it “connection”)
published_date Date Date on which the review was published (as stated by the source)
published_date_estimated Boolean Whether the date was estimated if the source uses imprecise dates
travel_date Date Date on which the reviewer travelled
source_name String Machine name of the review source
title String Title of the review
ratings Array Array containing the review ratings
sentiment String Overall review sentiment
sentiment_score Float Score of the review sentiment, also considering sentiment without a topic
language String Language code of the review comment
language_name String Language name
recommend Boolean Recommendation status
reviewer Hash Object containing reviewer details
reservation_number Integer Reviewer’s reservation number
review_origin String Where the review originated from (3rd party soliciting)
travel_type String Travel type (business, leisure, etc)
travel_composition String Travel composition (friends, family, etc)
comments Array Review comments and management response
opinions Array Opinions analysed from the review title and comments
respond_url String URL to the extranet or a directly to the review respond form on the source

Published Date

Most sources provide a published date with each reviews. In some cases imprecise dates (e.g. “3 days ago”) are used. In very rare cases no details are given. In those cases Olery estimates the published date based on the available information. The published_date_estimated field informs you of this.

Do not confuse the published date with the created_at. The latter is the timestamp of when the review was created in our database.

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

Languages

The language field contains the ISO 639-1 code of the language. For example, for Dutch this will be “nl” and for German it will be set to “de”. See the following resources for more information:

The language field may be empty if no language could be detected.

Recommendation Statuses

On some sources (e.g. Facebook) the reviewer can state that they recommend going to a property. In such a case the recommend field is set to the boolean true. If the reviewer recommends not going to the property then the value is set to false. If nothing was specified this field is left empty.

Comments

Reviews can have one or more comments. If the source asks the reviewer to write in different sections, then those are divided into different comments. The kind indicates the type of comment.

Common kinds:

Management Responses

Management responses can be found as comments with the kind manager. In general, Olery captures management responses at least until the review becomes 30 days old. Some sources provide the published time of the response.

Field Data Types Description
kind String Kind of comment
comment String Full comment’s text
published_time Time If available on the source, the time management response was published

Reviewers

The reviewer object contains details about the reviewer. Currently the following fields are set:

Field Data Types Description
name String Name of the reviewer
email String Email address of the reviewer
origin String Raw origin of the reviewer
country Hash Extracted country of the reviewer

The country object has the following fields:

Field Data Types Description
code String ISO 3166 A2 code of the country
name String Name of the country in English

Some of these fields may be empty (including the country object) if either no data was specified or no data could be determined based on the specified data (e.g. no country could be determined).

The reviewer’s personal information might also be empty for privacy protection if you are not an authorized user.

Review Origins

The review_origin field contains the origin of the original review. This is not to be confused with the review source. As an example, users of Olery Feedback can submit survey responses to review websites such as HolidayCheck and Zoover. In such a case the review_origin field is set to olery, otherwise it’s either set to the review source name (e.g. “zoover”) or left empty if it could not be determined where the review came from.

Example Output 

    {
      "count": null,
      "next_url": "https://agora.olery.com/v3/companies/123/reviews?page=2",
      "data": [
        {
          "id": 179769976,
          "review_id": "aff10a85acaa69e5004e599dbc34109a0ec6efb9",
          "id_on_review_site": "4330235082",
          "reservation_number": "1130008153",
          "published_date": "2017-01-30",
          "travel_date": null,
          "source": "book-hotel.com",
          "connection_url": "http://www.book-hotel.com/hotel/nl/hotel.html",
          "review_origin": null,
          "respond_url": "https://admin.book-hotel.com/hotel/hoteladmin/general/reviews.html",
          "language": "en",
          "language_name": "English",
          "reviewer": {
            "name": "Nils",
            "email": null,
            "origin": "Germany",
            "country": {
              "code": "DE",
              "name": "Germany"
            }
          },
          "travel_type": null,
          "travel_composition": null,
          "recommend": null,
          "title": "Welcoming, but the night was the worst in a while.",
          "comments": [
            {
              "kind": "good",
              "comment": "“Friendly people, international flair, welcoming atmosphere.”"
            },
            {
              "kind": "bad",
              "comment": "Sorry, but this hotel has extremely thin walls."
            }
          ],
          "ratings": [
            {
              "category": "overall",
              "topic": "overall_general",
              "title": "General",
              "rating": 71
            },
            {
              "category": "location",
              "topic": "location_general",
              "title": "Location General",
              "rating": 50
            },
            {
              "category": "room",
              "topic": "comfort",
              "title": "Comfort",
              "rating": 75
            },
            {
              "category": "cleanliness",
              "topic": "cleanliness_general",
              "title": "Cleanliness General",
              "rating": 100
            }
          ],
          "sentiment": "negative",
          "sentiment_score": -0.0909090909090909,
          "opinions": [
            {
              "topics": [
                "staff"
              ],
              "polarity": "neutral",
              "strength": 1
            },
            {
              "topics": [
                "bed",
                "room",
                "sleeping_comfort"
              ],
              "polarity": "positive",
              "strength": 1
            },
            {
              "topics": [
                "noise"
              ],
              "polarity": "negative",
              "strength": 1
            }
          ],
          "created_at": "2017-01-31T02:07:37.830+00:00",
          "updated_at": "2017-01-31T02:37:57.778+00:00"
        }
      ]
    }

Parameters

Parameter Parameter Type Data Types Required Description
id path Integer true ID of the company
since query DateTime false Return reviews created or updated after this datetime, ISO 8601 format.
start_date query Date false Start date of a period in which reviews were published, ISO 8601 format
end_date query Date false End date of a period in which reviews were published, ISO 8601 format
sources query Array false Sources to filter by, comma-separated

All the date parameters use UTC whenever the timezone is not given

Response Statuses

Status Code Reason
200 OK
404 Specified company was not found
403 You do not have access to the company

Response Fields

Field Data Types Description
count Integer Total amount of reviews
data Array List of reviews