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:
- 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.
- 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.
- 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.
- Also, there is an endpoint to tell us if we have missed a review source or connected the property to the wrong profile.
- 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.
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:
You should have received the group ID for your account from the Olery
support (firstname.lastname@example.org). Let’s say it’s
123 and your authentication
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),
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:
Use the id you saved from the activation response. Don’t forget to add the auth token.
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
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 and Updated Reviews
Now that you have the review history, you want to regularly import new reviews.
For this it is important to understand two things:
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:
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
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
- at the next scheduled sync (best hourly), make a request and use
sinceset to the
- save the new
- rinse and repeat
This is a very efficient way to receive all data while avoiding any data gaps.
A request could look like this:
For review updates, the full review will reappear in the response. Be prepared to override all existing data.
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
so the same approach as with the reviews can be used.
A request would look like this:
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.
If you want to stop receiving data for a property you can do so with a simple DELETE request:
You will instantly lose access to the property and billing with be updated with the next cycle.
Check out the deactivation endpoint documentation