Tips and tricks
Pagination
To provide the best experience, we decided to split our results into pages. This will avoid transferring massive amounts of data in a single API call.
- Always start requesting data with the
page_number
parameter set to1
(default value). - The amount of available pages depends on the
per_page
parameter value and the total amount of data. - The API response contains a
pages
key with the total amount of available pages. - Make sure to stop paginating once the page limit is hit.
We do not charge for pagination requests.
Paginating reviews
To deliver correct results, we introduced a diff
parameter.
To access the next page, you must provide the diff
parameter.
Its value is always present in the response from the previous request (previous page).
Paginating profiles
To paginate profiles, you do not need diff
parameter.
The review profiles are grouped by location. The per_page
parameter tells us, how many
locations would you like to retrieve in one page. Please note, that one location can
contain up to 8 review profiles.
How to avoid being charged for pagination
You only pay for the initial request. Once you have paid for your data, you can paginate them,
request time series, filter different review sites, and use other available options that the endpoint offers.
The way we decide whether to charge for the request or not is to see the company_name
, company_domain
,
and ticker_symbol
combination. If you have not yet requested a company X (e.g., McDonald’s),
you will get charged for it. But you will not get charged for the following requests
related to the company X (e.g., McDonald’s). However, if you change the combination of already mentioned
parameters, you will get charged again as it might produce different results.
Update and callback functionality
If you need to get the latest data, we need the time to fetch them. Whenever you request an update on the data, we enqueue this job for processing. Depending on the number of profiles to update, this might take seconds to several minutes. Instead of polling our servers for the status, we hit your callback URL once we have data ready for you. You can expect the first page of the data when it is prepared.
If you do not wish to receive the latest data and are happy with what we have available,
you can skip the update
parameter. We will deliver a response immediately, and there is no need for a callback URL.
We POST payload to the given callback URL. The payload follows the JSON response structure for the data you initially requested. Please see the documentation of each endpoint to see the JSON response structure.
Request ID
To keep track of existing jobs and be able to debug them, we provide a unique identifier for every request you submit. You can use this ID to refer to your request.