Olery Developer Portal logo Olery Developer Portal

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

The endpoint returns individual reviews and their meta data.

Filtering by Dates

By default all available reviews are returned. When specifing a start_date and end_date only reviews published within that period are returned.

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 2 hour import cycle. Run an import, save the time and use it to fill the since paramenter in the next cycle.

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.

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 The storage ID of the review, preserved on review updates.
review_id String The unique ID of the review. This is generated from the review site and may change.
id_on_review_site String The ID of the review on the review source.
connection_url String The URL of the property on the source website (connection).
published_date Date The 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 The date on which the reviewer travelled.
source_name String The machine name of the review source.
title String The title of the review.
ratings Array Array containing the review ratings.
sentiment String The overall review sentiment (aggregation of the opinions).
sentiment_score Float Score of the review sentiment.
language String The language of the review.
recommend Boolean The recommendation status.
reviewer Hash Object containing reviewer details.
reservation_number Fixnum The reviewer’s reservation number.
review_origin String Where the review originated from (3rd party soliciting).
travel_type String The travel type (business, leisure, etc).
travel_composition String The travel composition (friends, family, etc)
language_name String The language title.
comments Array The review comments and management response.
opinions Array The opinions analysed from the review title and comments.
respond_url String The url to the extranet or a directly to the review respond form on the source.

When a client doesn’t have access to any companies the data key will contain an empty array.

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

By using the limit parameter the number of reviews per page can be manipulated. We recommend setting it to 100, not higher.

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.

Ratings

The “ratings” field is an array with objects for each subrating. The rating itself is an integer with a scale of 0 to 100. Rating objects without values are not included in the array.

Each subrating is in 1 out of 9 categories. Understand these cateogries as a suggestion by Olery. You can aggregate the ratings for the categories to make the number of rating topics more manageble for the user.

Fields for each subrating:

Field Data Types Description
category String The category of the rating.
topic String The machine name of the rating.
title String The human-friendly title of the rating.
rating Fixnum The rating itself.

Sentiment

All reviews with written content in English, German, French, Dutch, Italian and Spanish get analyzed for the reviewer’s sentiment.

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.

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 The topics the opinion is about.
polarity String The polarity of the opinion.
strenth Fixnum The strength of the opinion (can take any value).

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

Sometimes a reviewer might 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:

Mangement Responses

Management responses can be found as comments with the kind “manager”. Olery captures management responses at least until the review becomes 30 days old.

Reviewers

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

Field Data Types Description
name String The name of the reviewer.
email String The Email address of the reviewer.
origin String The raw origin of the reviewer.
country Hash Information about the country of the reviewer.

The country object has the following fields:

Field Data Types Description
code String The ISO 3166 A2 code of the country.
name String The full 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).

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 Fixnum true The ID of the company.
limit query Fixnum false The number of reviews per page.
since query Time false Reviews created after this date and time are returned.
start_date query Date false The start date in ISO 8601 format.
end_date query Date false The end date in ISO 8601 format.
sources query Array false Optional sources to filter by.
min_rating query Fixnum false The minimum required rating of a review.
max_rating query Fixnum false The maximum required rating of a review.
language query String false The language code to limit reviews to.
sentiment query String false The sentiment to limit reviews to.
subratings query Hash false Subratings associated to parent ratings.
topic query String false The rating topic to filter by, defaults to “overall”

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
count Fixnum The total amount of reviews.
data Array The list of reviews.