Overview
With the AppFollow API you can use the Rating History method for exporting ratings.
You can retrieve incremental and total rating data. Below, we'll cover the differences between these methods and help determine which one is better to use depending on your goal.
Please note that the previously available methods Ratings and Ratings Export have been deprecated. We encourage you to use the Rating History API method for all your ratings data retrieval needs.
What are Incremental and Total (Cumulative) Ratings
If you need to know how many stars an app received on a certain date or during a specific timeframe (week, month) you need to export the incremental ratings.
The total is the sum of your app’s lifetime rating on the specified dates. If the timeframe is specified (week, month), it shows the app’s total average rating at the end of the selected timeframe.
When using the Rating History method, the type of the rating is set through an optional parameter – type – which can be set to total (Total) or diff (Incremental).
Type parameter is described as a calculation strategy to be applied for ratings.
* diff for incremental changes in ratings between two consecutive dates
* total for a total amount of ratings for a particular date
Rating History API Method
You can use this method to get the total or incremental ratings (additional parameter type=total or diff) for Google Play, App Store, Mac App Store, Microsoft Store or Amazon apps.
Required parameters:
- collection_name: The name of your workspace as it appears in the URL bar of your browser.
-
ext_id: store ID of your app.
for App Store — this is 9-10 digits identification number;
for Google Play — this is bundle name;
for Microsoft Store — this is 12 characters consisting of letters and numbers;
for Amazon — this is 10 characters consisting of capital letters and numbers. - store: as for Appstore, gp for Google Playstore, ms for Microsoft Store, am for Amazon, mc for Mac App Store.
Additional parameters:
- country: Two letter country code (us, gb, de, etc.) Full list
- period: Data granularity: daily, weekly, or monthly
- version: App version (for App Store apps or Google Play with Google Play Console integration) e.g. 1.1.1
- type: diff for Incremental rating or total for total rating
- from: Starting date of the request, year-month-day format.
- to: End date of the request, year-month-day format.
- Include_negative_changes: Include negative changes in ratings over the given period (for Google Play, incremental rating by country)
- limit: By default the limit is 10, which means the request will only return 10 records. For example, if your query includes the “daily” parameter and a 60 day time period, then you will need to set the limit to 60 since each day is 1 record.
- offset: This parameter can be used in combination with the “limit” value for any pagination needs. For example, if you have 1000 records and you would like to get 100 at a time, you would add &limit=100 to the first request to limit the number of records.
To get the next 100 records, you will add &offset=100&limit=100. This will skip records 0-100 and will show you records 101-200. Then for each subsequent request you increase the offset by 100 (offset=200 to get 201-300, offset=300 to get 301-400, etc.) This parameter is also used for very large requests that might come back with a timeout error.
Example request to get daily incremental ratings from the Google Playstore for Germany:
Same request with offset and limit to skip the first 100 records and with a limit of 100:
Response Body Parameters:
The response body parameters will be listed in this section of the API documentation.