The /reports/ratings resource provides detailed access to current and historic ratings for any apps in a variety of formats.
The main resource gives you a single combined result across the filter parameters you select. The result can be limited by dates, products, and countries.
Using the group_by parameter, you can get a report broken down by products, countries, dates, or any combination thereof.
Scope: All of the resources in this route require read access in the public scope (public:read).
The Public Data API add-on is required to access data for products that are not owned by your account. Free accounts must use the Public Data API, even for products that are in their account.
Getting Simple Totals
Request
GET /reports/ratings/?group_by={group_by}&start_date={start_date}&end_date=(end_date)&granularity={granularity}&products={product_ids}&countries={countries}&format={format}
Arguments
| Argument | Type | Description |
|---|---|---|
| start_date | Date | (yyyy-MM-dd) Date, inclusive, to start reporting from. If you specify a granularity other than daily this will be rounded down to the nearest period. default: the first date we have data for. |
| end_date | Date | (yyyy-MM-dd) Date, inclusive, to stop reporting. If you specify a granularity other than daily this will be rounded up to the nearset period. default: yesterday. |
| group_by | List | One or more pivots separated by a comma (,). Available pivots: product, country, date. |
| products | List | (productId | productId1, productId2, …) specific products to include in the response, default: all active products in account |
| countries | List | (isoCode1, isoCode2, …) Countries to limit the report to (can be taken from /data/countries, default: include all countries) |
| format | String | Output format: JSON or CSV. Defaults to JSON.
Note: To prevent excessive repetition, when format=csv sub-object (like the product in /sales/products/…) the object will not be fully serialized but only its reference will be. |
Response
| Field | Type | Description |
|---|---|---|
| breakdown | Array | An array listing the number of total ratings by star, where index 0 = 1 star and index 4 = 5 stars. These are the ratings that were observed on the last day of the given time period. If the report is broken down by date, these are the ratings that were observed on the source app store on the result date. |
| new | Number | An array listing the number of new ratings by star, where index 0 = 1 star and index 4 = 5 stars. These are the ratings that were added in the given time period. If the report is broken down by date, these are the ratings that were added since the preceding day. |
| average | Number | A double representing the weighted average of all ratings. |
| total | Number | An int representing the total number of times the app has been rated. |
| new_average | Number | A double representing the weighted average of ratings received in the selected time period. |
| new_total | Number | An int representing the number of times the app was rated in the selected time period. |
| positive | Number | An int representing the total number of 4 and 5 star ratings. |
| negative | Number | An int representing the total number of 1 and 2 star ratings. |
| neutral | Number | An int representing the total number of 3 star ratings. For the sake of consistency. |
| new_positive | Number | An int representing the number of 4 and 5 star ratings received in the selected period. |
| new_negative | Number | An int representing the number of 1 and 2 star ratings received in the selected period. |
| new_neutral | Number | An int representing the number of 3 star ratings received in the selected period. For the sake of consistency. |
Example
// GET /reports/ratings?start=2018-06-01&end=2018-06-30
{
"breakdown": [ /* observed ratings on 6/30 */
5860419,
1431510,
2802529,
6458451,
44737094
],
"new": [ /* new ratings in range 6/01 - 6/30 */
163812,
52324,
120262,
300016,
2779912
],
"average": "4.35",
"total": 61290003,
"new_average": "4.60",
"new_total": 3416326,
"positive": 51195545,
"negative": 7291929,
"neutral": 2802529,
"new_positive": 3079928,
"new_negative": 216136,
"new_neutral": 120262
}
Generating a Report By Product, Country, or Date
Request
GET /reports/ratings/?group_by={group_by}&start_date={start_date}&end_date=(end_date)&granularity={granularity}&products={product_ids}&countries={countries}&format={format}
Arguments
| Argument | Type | Description |
|---|---|---|
| start_date | Date | (yyyy-MM-dd) Date, inclusive, to start reporting from. If you specify a granularity other than daily this will be rounded down to the nearest period. default: the first date we have data for. |
| end_date | Date | (yyyy-MM-dd) Date, inclusive, to stop reporting. If you specify a granularity other than daily this will be rounded up to the nearset period. default: yesterday. |
| group_by | List | One or more pivots separated by a comma (,). Available pivots: product, country, date. |
| products | List | (productId | productId1, productId2, …) specific products to include in the response, default: all active products in account |
| countries | List | (isoCode1, isoCode2, …) Countries to limit the report to (can be taken from /data/countries, default: include all countries) |
| format | String | Output format: JSON or CSV. Defaults to JSON.
Note: To prevent excessive repetition, when format=csv sub-object (like the product in /sales/products/…) the object will not be fully serialized but only its reference will be. |
Specifying a
group_bythat includes date without a start or end will default the start and end dates to the past 30 days.
Response
The response depends on the specified group_by given. No matter which group_by, the deepest part of the representation is similar to the representation you’d get if you don’t specify any grouping (like what you see above).
Here are a few examples of different groupings:
Example Response For Ratings By Date
// GET /reports/ratings/?group_by=dates
{
"2018-07-14": {
"breakdown": [
3103800,
644453,
1377936,
3303381,
25455786
],
"new": [
7811,
2224,
4655,
10910,
96185
],
"average": "4.40",
"total": 33885356,
"new_average": "4.52",
"new_total": 121785,
"positive": 28759167,
"negative": 3748253,
"neutral": 1377936,
"new_positive": 107095,
"new_negative": 10035,
"new_neutral": 4655,
"date": "2018-07-14"
},
"2018-07-14": {
...
}
}
Example For Ratings By Product + Date
// GET /reports/ratings?group_by=products,dates
{
"5558400": {
"2018-07-14": {
"breakdown": [
554754,
143233,
306225,
660234,
3192830
],
"new": [
586,
97,
169,
319,
1933
],
"average": "4.19",
"total": 4857276,
"new_average": "3.94",
"new_total": 3104,
"positive": 3853064,
"negative": 697987,
"neutral": 306225,
"new_positive": 2252,
"new_negative": 683,
"new_neutral": 169,
"product_id": 5558400,
"date": "2018-07-14"
},
...
},
"61519001": {
"2018-07-14": {
...
}
}
},