Ratings

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 private scope (private:read).

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_by that 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": {
        ...
        }
    }
},