Overview

Do you want to build reputation management features into your application? For example, a page where users can read and react to reviews guests published for their business.

You have come to the right place. The following guide is supposed to give you a quick overview of all the steps involved. Please also refer to the documentation of the individual endpoints for details.

Let’s get started.

Assume you want to monitor the reviews of a hotel. These are the essential steps you need to take care of:

1. You need to activate the hotel on your Olery account, so we can capture all the reviews and provide you with access to them. This can be done via the API.
2. You probably want the review history of the hotel, so you need to import all past reviews into your database. We provide the raw reviews and a lot of metadata in a structured format. We do not provide aggregated data in endpoints (e.g. for a “number of reviews per month” chart), you have to do that in your application.
3. Then you will want to stay synced with all the new reviews, so you need to check the API regularly for new or updated reviews.
4. Also, there is an endpoint to tell us if we have missed a review source or connected the property to the wrong profile.
5. If, at some point, you are not interested in the hotel anymore, you can deactivate it. We will then stop charging our monthly property fee.

Let’s get into the details.

Activate Property

Before you can start requesting data for a property, you have to activate it.

What happens at activation

Activating a property triggers a few things on our end:

• you immediately get API access to the property which should already exist in our database
• we start a semi-automatic process of finding all profiles of these properties on the supported sources (this might take up to 5 days to complete)
• we promote the property to a 12-hour review collection cycle if not already so

In most cases, there is some but not all data is available for a newly activated property. It is possible that there is no data at all. Be prepared to wait up to 5 days until all data is available in the API.

How to activate

To be able to activate a property, you need to tell us exactly which property you mean. Because names are not unique, we’re using TripAdvisor IDs to identify properties.

Therefore, the activation API request requires a TripAdvisor ID or URL (which contains the ID).

The base URL for the POST request looks like this:

https://agora.olery.com/v3/groups/:id/companies

You should have received the group ID for your account from the Olery support (support@olery.com). Let’s say it’s 123 and your authentication token is 456:

https://agora.olery.com/v3/groups/123/companies?auth_token=456

Now add the TripAdvisor URL of the property to activate. It’s Hotel Casa Amsterdam in this example. You also want us to search for new connections (URLs to the profile of the hotel on the different sources), so set request_connections=true:

https://agora.olery.com/v3/groups/123/companies?auth_token=456&trip_advisor_urls=https://www.tripadvisor.com/Hotel_Review-g188590-d232326-Reviews-Hotel_Casa-Amsterdam_North_Holland_Province.html&request_connections=true

Save the ID

Perfect! You have made the request and the property is now active. You will now be billed for it and it has to stay active for at least 30 days.

In the API response you will find the id field. This is Olery’s internal property ID. Save it, you will need to specify it on all data requests.

Check out the activation endpoint documentation

Import Review History

Now that you have access, you want to import all past reviews, the review history. The Review Feed API endpoint provides a chronological list of all reviews from all sources with all details and metadata in a standardized format.

The base URL is very simple:

https://agora.olery.com/v3/companies/:id/review_feed

Use the id you saved from the activation response. Don’t forget to add the auth token.

Pagination

You always receive up to 20 reviews in the response, so be prepared to deal with pagination. Follow the next_url field or use the page= parameter. There can be hundreds of pages!

To import the history, simply go through all pages and save the reviews.

Learn more about the review format on the review feed endpoint documentation

Import New, Updated, and Deleted Reviews

Now that you have the review history, you want to regularly import new reviews.

For this it is important to understand two things:

Review Updates

When we collect a review it is immediately available in the API response, even if it still undergoes processing and analysis.

This means that a review is likely to receive updates in the minutes, hours and days after it was collected. Therefore, it’s important that you synchronize any updates with your database.

See the images below for a possible timeline on review updates:

Deleted Reviews

To ensure the integrity and trustworthiness of review platforms, sources constantly monitor and remove spam or fraudulent reviews.

Our collection system diligently tracks these deletions from the sources. We strive to maintain an up-to-date mirrored version of the reviews as they appear on the original source, reflecting both additions and deletions.

To facilitate the synchronization of these deleted reviews, we provide a dedicated endpoint that returns a list of review IDs that have been removed from our database.

For detailed information regarding the ‘deleted reviews’ endpoint, please refer to the reviews deleted

New Old Reviews

Sometimes there are also new reviews available with old (published) dates.

This can happen in these cases:

• we have added a new connection to a source and are collecting its review history
• the source publishes some old reviews for whatever reason

Be prepared to save reviews with old dates.

How to incremental imports and updates

To make it easy for you to receive and save new reviews and updates, you should use the since parameter.

When requesting the Review Feed with this parameter, the response will only contain reviews created (in our database) or updated since the given timestamp. This way you get an incremental data feed.

This is the proposed flow:

• make the requests to import the review history
• save the time of the first request as last_synced
• at the next scheduled sync (best hourly), make a request and use since set to the last_synced timestamp
• save the new last_synced
• rinse and repeat

This is a very efficient way to receive all data while avoiding any data gaps.

A request could look like this:

https://agora.olery.com/v3/companies/789/review_feed?since=2019-03-01T16:00:00Z

For review updates, the full review will reappear in the response. Be prepared to override all existing data.

Update Frequency

We collect reviews from all sources every 12 hours, but the exact timing is unpredictable. Additional, there are the mentioned updates due to processing.

Therefore, we recommend you to set up a schedule to sync once every hour.

Import Source Data

Besides reviews, we’re providing some additional data for some sources. This data is stored as day time series. Therefore, you only need to import it once a day (best at end of day). It supports the same since parameter, so the same approach as with the reviews can be used.

A request would look like this:

https://agora.olery.com/v3/companies/789/source_data?since=2019-03-01

Check out the source data endpoint documentation

Make Connection Suggestions

You can see all the availble sources and active connections for the hotel with the Company Sources endpoint.

If we’re missing a connection to a supported source or you want to update an incorrect connection URL, please see the Connection Suggestion documentation. All suggestions are manually moderated.

It is possible to use these endpoints to build an interface to “manage” connections for your support staff and/or the end users.

Deactivate Property

If you want to stop receiving data for a property you can do so with a simple DELETE request:

https://agora.olery.com/v3/groups/123/companies/789

You will instantly lose access to the property and billing with be updated with the next cycle.

Check out the deactivation endpoint documentation