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

Filtering by Dates

By default all available reviews are returned. When specifying 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, remember the time and use it to fill the since parameter 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 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

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 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
category String Suggested category of the rating
topic String Machine name of the rating
title String Human-friendly title of the rating
rating Integer Rating value

Sentiment

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

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 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 Topics the opinion is about
polarity String Polarity of the opinion
strength Integer 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:

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.

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
limit query Integer false Number of reviews per page
since query DateTime false Reviews created or updated after this date and time are returned
start_date query Date false Start date in ISO 8601 format
end_date query Date false End date in ISO 8601 format
sources query Array false Sources to filter by
min_rating query Integer false Minimum overall rating of reviews to be returned
max_rating query Integer false Maximum overall rating of reviews to be returned
language query String false Language code to limit reviews to
sentiment query String false Sentiment to limit reviews to.
topic query String false Sentiment topic present in the opinions of the reviews to be returned

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