Getting Ratings Through the API

Maria

Updated January 31, 2022 16:13

Overview

The AppFollow API provides two methods for exporting ratings: 9. Ratings and 28. Ratings Export. 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.

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 API, the type of the rating is set through an additional parameter – type – which can be set to total (Cumulative data) or diff (Incremental data).

For iOS apps, if the parameter type is not specified, by default method 9. Ratings provides the total ratings (Cumulative data) and method 28. Ratings Export provides diff ratings (Incremental data).
For Android apps, to get the total ratings (Cumulative data), you should use method 9. Ratings with the additional parameter type — total and specify the country. To get the incremental ratings, you should use method 28. Ratings Export, only worldwide data is available (the country parameter is not required).

API Methods for Ratings Export

9. Ratings

You can use this method to get the Total ratings (additional parameter type=total) for App Store and Google Play apps.
To retrieve the Incremental data, you can use this method only for the App Store apps (additional parameter type=relative). This method allows getting Incremental data only on a certain date (additional parameter date) or for the last 31 days by default if the date parameter is not set.
To get the Incremental data for a Google Play app, please use method 28. Ratings Export.

Required parameters:

ext_id — app external ID:

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.

Additional parameters:

date — date in format: YYYY-MM-DD
country — country code e.g. us (for App Store or Microsoft Store or Amazon apps only) Full list
type — total (Cumulative data) DEFAULT, relative.

28. Ratings export

Required parameters:

COLLECTION_NAME — name of the workspace your app is added (part of the url);
ext_id — app external ID:
for App Store — this is 9-10 digits identification number;
for Google Play — this is bundle name.

Additional parameters:

country — country code e.g. us Full list
from — date in format: YYYY-MM-DD (used with 'to' parameter)
to — date in format: YYYY-MM-DD (used with 'from' parameter)
period — day, week or month
version — app version (for App Store apps or Google Play with Google Play Console integration) e.g. 1.1.1
type — total (Cumulative data), diff (Incremental data is by default)

Google Play: Because of new rating system, country parameter is required to get the reliable data. Please specify it by using "&country=us" parameter.)

Examples

Incremental ratings

App Store app, method 9. Ratings

Example: we need to get the ratings for an iOS app received in the US on a certain date – January 15, 2022.

Screenshot_2022-01-31_at_21.29.32.png

Example of the request: https://api.appfollow.io/ratings?ext_id=XXXXXXXXXXX&country=us&type=relative&date=2022-01-15

Response:

{
"ratings": {
"list": [
{
"date": "2022-01-15",
"stars3": 1,
"country": "us",
"stars2": 0,
"stars1": 4,
"stars_total": 32,
"stars5": 18,
"version": "3.43.0",
"rating": "4.16",
"stars4": 9
}
],
"store": "as",
"ext_id": "XXXXXXXXXX"
}
}

App Store app, method 28. Ratings export

Example: we need to get the ratings for an iOS app received in the US during the week of January 10 - 16, 2022.

Screenshot_2022-01-31_at_21.34.14.png

In the example, the app is added to the workspace "AppFollow apps". You can check the COLLECTION_NAME parameter in the workspace URL here:

Example of the request: https://api.appfollow.io/appfollow-apps/ratings_export?ext_id=XXXXXXXXXXX&country=us&type=diff&period=week&from=2022-01-10&to=2022-01-16

Response:

{
"ratings": {
"country": "us",
"type": "diff",
"title": null,
"from": "2022-01-10",
"ext_id": "XXXXXXXXXX",
"to": "2022-01-16",
"store": "itunes",
"period": "week",
"list": [
{
"stars3": 10,
"stars5": 267,
"stars2": 5,
"stars": 340,
"stars1": 11,
"date": "Jan 10 - Jan 16",
"avg_rating": 4.629,
"stars4": 47
},
{
"stars4": 47,
"date": "Total",
"avg_rating": 4.629,
"stars1": 11,
"stars": 340,
"stars5": 267,
"stars2": 5,
"stars3": 10
}
]
}
}

Google Play, method 28. Ratings export

To use this method, the app needs to have an active Ratings Integration with the Google Play Console.

Example: we need to get the App Watcher Android app Worldwide ratings during the week of January 10 - 16, 2022.

Screenshot_2022-01-27_at_13.16.10.png

In the example, the app is added to the workspace "AppFollow apps". You may check the COLLECTION_NAME parameter in the workspace URL here:

Example of the request: https://api.appfollow.io/appfollow-apps/ratings_export?ext_id=com.anod.appwatcher&type=diff&from=2021-12-31&to=2022-01-27&period=week

Response:

{
"ratings": {
"from": "2022-01-10",
"type": "diff",
"title": null,
"ext_id": "com.anod.appwatcher",
"list": [
{
"stars4": 0,
"stars1": 0,
"avg_rating": 5,
"date": "Jan 10 - Jan 16",
"stars2": 0,
"stars5": 7,
"stars": 7,
"stars3": 0
},
{
"stars4": 0,
"avg_rating": 5,
"date": "Total",
"stars1": 0,
"stars": 7,
"stars5": 7,
"stars2": 0,
"stars3": 0
}
],
"store": "googleplay",
"to": "2022-01-16",
"period": "week"
}
}

Total ratings

App Store app, method 9. Ratings

Example: we need to get the rating for an iOS app that was on the public app page in the US on January 15, 2022.

Screenshot_2022-01-31_at_21.38.27.png

Example of the request: https://api.appfollow.io/ratings?ext_id=XXXXXXXXXXX&country=us&type=total&date=2022-01-15

Response:

{
"ratings": {
"list": [
{
"stars1": 4072,
"version": "3.43.0",
"country": "us",
"stars_total": 140547,
"stars2": 2484,
"stars4": 19212,
"stars5": 108476,
"stars3": 6303,
"rating": 4.605,
"date": "2022-01-15",
"review_rating": 3.17
}
],
"ext_id": "XXXXXXXXXX",
"store": "as"
}
}

App Store app, method 28. Ratings export

Example: we need to get the total ratings for an iOS app in the US for December, 2021. This means the total rating that was on the public app page in the store at the end of the month - 31 December.

Screenshot_2022-01-31_at_21.40.56.png

In the example, the app is added to the workspace "AppFollow apps". You may check the COLLECTION_NAME parameter in the workspace URL here:

Example of the request: https://api.appfollow.io/appfollow-apps/ratings_export?ext_id=XXXXXXXXXXX&country=us&type=total&period=month&from=2021-12-01&to=2021-12-31

Response:

{
"ratings": {
"list": [
{
"stars": 139852,
"stars2": 2478,
"date": "Dec 2021",
"stars5": 107925,
"stars3": 6280,
"stars4": 19129,
"stars1": 4040,
"avg_rating": 4.605
},
{
"stars2": 2478,
"date": "Total",
"stars4": 19129,
"stars5": 107925,
"stars3": 6280,
"stars1": 4040,
"avg_rating": 4.605,
"stars": 139852
}
],
"type": "total",
"period": "month",
"from": "2021-12-01",
"title": null,
"ext_id": "XXXXXXXXXX",
"store": "itunes",
"country": "us",
"to": "2021-12-31"
}
}

Google Play, method 9. Ratings

This method should be used in the workspace without Google Play: Ratings Integration set for the app.

Example: we need total ratings for the App Watcher Android app, Russia on January 15, 2022. This means the total rating that was on the public app page in the store at the end of this date.

Screenshot_2022-01-27_at_21.13.31.png

Example of the request: https://api.appfollow.io/ratings?ext_id=com.anod.appwatcher&country=ru&type=total&date=2022-01-15

Response:

{
"ratings": {
"store": "gp",
"ext_id": "com.anod.appwatcher",
"list": [
{
"stars4": 104,
"stars1": 65,
"rating": 4.435,
"stars3": 39,
"version": "1.4.7",
"stars2": 52,
"review_rating": 3.971,
"stars_total": 1058,
"date": "2022-01-15",
"country": "ru",
"stars5": 798
}
]
}
}

Google Play, method 28. Ratings export

Example: we need total ratings for the App Watcher Android app in Russia for December, 2021. This means the total rating that was on the public app page in the store on at the end of the month - 31 December.

Screenshot_2022-01-27_at_21.18.57.png

Example of the request: https://api.appfollow.io/appfollow-apps/ratings_export?ext_id=com.anod.appwatcher&country=us&type=total&period=month&from=2021-12-01&to=2021-12-31

Response:

{
"ratings": {
"period": "month",
"ext_id": "com.anod.appwatcher",
"type": "total",
"to": "2021-12-31",
"store": "googleplay",
"title": null,
"list": [
{
"avg_rating": 4.441,
"stars5": 796,
"date": "Dec 2021",
"stars": 1051,
"stars1": 64,
"stars4": 102,
"stars3": 38,
"stars2": 51
},
{
"stars2": 51,
"stars3": 38,
"stars": 1051,
"stars1": 64,
"stars4": 102,
"stars5": 796,
"date": "Total",
"avg_rating": 4.441
}
],
"from": "2021-12-01"
}
}

Was this article helpful?

0 out of 0 found this helpful

Overview

What are Incremental and Total (Cumulative) Ratings

API Methods for Ratings Export

9. Ratings

28. Ratings export

Required parameters:

Examples

Incremental ratings

App Store app, method 9. Ratings

App Store app, method 28. Ratings export

Google Play, method 28. Ratings export

Total ratings

App Store app, method 9. Ratings

App Store app, method 28. Ratings export

Google Play, method 9. Ratings

Google Play, method 28. Ratings export

Was this article helpful?

Related articles