Ratings | App Store API

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.

Important: Google Play no longer exposes the absolute number of ratings by star, or the total number of ratings by country. As such, star counts are not available any total ratings are only available when the country filter is not used.

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. This array returns nulls for Android apps from Google Play.
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. This array returns nulls for Android apps from Google Play.
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. This value will be null when an Android app from Google Play is selected and the country filter is used.
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. This value will be null when an Android app from Google Play is selected and the country filter is used.
positive	Number	An int representing the total number of 4 and 5 star ratings. This value will be null when an Android app from Google Play is selected.
negative	Number	An int representing the total number of 1 and 2 star ratings. This value will be null when an Android app from Google Play is selected.
neutral	Number	An int representing the total number of 3 star ratings. This value will be null when an Android app from Google Play is selected.
new_positive	Number	An int representing the number of 4 and 5 star ratings received in the selected period. This value will be null when an Android app from Google Play is selected.
new_negative	Number	An int representing the number of 1 and 2 star ratings received in the selected period. This value will be null when an Android app from Google Play is selected.
new_neutral	Number	An int representing the number of 3 star ratings received in the selected period. This value will be null when an Android app from Google Play is selected.
one_star_percent	Number	A double representing the share of 1-star ratings as of the date. If `the response isn’t broken down by date this will be the value as of the end of the selected range.
two_star_percent	Number	A double representing the share of 2-star ratings as of the date. If `the response isn’t broken down by date this will be the value as of the end of the selected range.
three_star_percent	Number	A double representing the share of 3-star ratings as of the date. If `the response isn’t broken down by date this will be the value as of the end of the selected range.
four_star_percent	Number	A double representing the share of 4-star ratings as of the date. If `the response isn’t broken down by date this will be the value as of the end of the selected range.
five_star_percent	Number	A double representing the share of 5-star ratings as of the date. If `the response isn’t broken down by date this will be the value as of the end of the selected range.

Example

// GET /reports/ratings?start_date=-30&products=280402920612

{
  "breakdown": [
    98019,
    28197,
    92923,
    339374,
    4766539
  ],
  "new": [
    1860,
    492,
    1233,
    5268,
    86944
  ],
  "average": "4.81",
  "total": 5325052,
  "new_average": "4.83",
  "new_total": 95797,
  "positive": 5105913,
  "negative": 126216,
  "neutral": 92923,
  "new_positive": 92212,
  "new_negative": 2352,
  "new_neutral": 1233,
  "one_star_percent": "0.02",
  "two_star_percent": "0.01",
  "three_star_percent": "0.02",
  "four_star_percent": "0.06",
  "five_star_percent": "0.90"
}

This is what the output will look like when an Android app from Google Play is selected:

// GET /reports/ratings?start_date=-30&products=41259149022

{
  "breakdown": [
    null,
    null,
    null,
    null,
    null
  ],
  "new": [
    null,
    null,
    null,
    null,
    null
  ],
  "average": "4.28",
  "total": 26383,
  "new_average": "0.00",
  "new_total": 123,
  "positive": null,
  "negative": null,
  "neutral": null,
  "new_positive": null,
  "new_negative": null,
  "new_neutral": null,
  "one_star_percent": "0.10",
  "two_star_percent": "0.04",
  "three_star_percent": "0.05",
  "four_star_percent": "0.11",
  "five_star_percent": "0.71"
}

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?start_date=-30&products=280402920612&group_by=date

{
  "2023-08-05": {
    "breakdown": [
      96228,
      27726,
      91744,
      334310,
      4682870
    ],
    "new": [
      69,
      21,
      54,
      204,
      3275
    ],
    "average": "4.81",
    "total": 5232878,
    "new_average": "4.82",
    "new_total": 3623,
    "positive": 5017180,
    "negative": 123954,
    "neutral": 91744,
    "new_positive": 3479,
    "new_negative": 90,
    "new_neutral": 54,
    "one_star_percent": "0.02",
    "two_star_percent": "0.01",
    "three_star_percent": "0.02",
    "four_star_percent": "0.06",
    "five_star_percent": "0.89",
    "date": "2023-08-05"
  },
  "2023-08-06": {
    ...
  }
}

Example For Ratings By Product + Date

// GET /reports/ratings?start_date=-30&products=280402920612&group_by=product,date

{
  "280402920612": {
    "2023-08-05": {
      "breakdown": [
        96228,
        27726,
        91744,
        334310,
        4682870
      ],
      "new": [
        69,
        21,
        54,
        204,
        3275
      ],
      "average": "4.81",
      "total": 5232878,
      "new_average": "4.82",
      "new_total": 3623,
      "positive": 5017180,
      "negative": 123954,
      "neutral": 91744,
      "new_positive": 3479,
      "new_negative": 90,
      "new_neutral": 54,
      "one_star_percent": "0.02",
      "two_star_percent": "0.01",
      "three_star_percent": "0.02",
      "four_star_percent": "0.06",
      "five_star_percent": "0.89",
      "product_id": 280402920612,
      "date": "2023-08-05"
    },
    "2023-08-06": {
     ...
    }
  }
}