Ratings

The /reports/ratings resource gives you current and historical ratings for any app, in JSON or CSV.

The main resource returns one combined result for the filters you select. You can limit it by date, product and country.

Use group_by to break the report down by product, country, date or any combination.

Caution

Note: Google Play no longer shows the number of ratings by star or the total number of ratings by country. Star counts aren’t available for Google Play apps, and total ratings are available only when you don’t filter by country.

Note

Scope: All resources in this route require the public:read scope.

Caution

You need the Public Data API add-on to access data for products your account doesn’t own. On a free account, you need it even for products in your 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 set a granularity other than daily, we round this down to the nearest period. Defaults to the first date we have data for.
end_date	Date	(yyyy-MM-dd) Date, inclusive, to stop reporting. If you set a granularity other than daily, we round this up to the nearest period. Defaults to yesterday.
group_by	List	One or more pivots separated by a comma (,). Available pivots: product, country, date.
products	List	(productId, productId1, productId2, …) Products to include in the response. Defaults to all active products in the account.
countries	List	(isoCode1, isoCode2, …) Countries to limit the report to. See /data/countries for codes. Defaults to all countries.
format	String	Output format: JSON or CSV. Defaults to JSON. Note: With format=csv, we don’t fully serialize nested objects (like the product in /sales/products/…). You get only a reference to each one, to cut down on repetition.

Response

Field	Type	Description
breakdown	Array	An array of total ratings by star, where index 0 = 1 star and index 4 = 5 stars. These are the ratings we saw on the last day of the period. If the report is broken down by date, these are the ratings we saw on the store on that date. This array returns nulls for Android apps from Google Play.
new	Number	An array of new ratings by star, where index 0 = 1 star and index 4 = 5 stars. These are the ratings added in the period. If the report is broken down by date, these are the ratings added since the day before. 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 is null for Android apps from Google Play when you filter by country.
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 is null for Android apps from Google Play when you filter by country.
positive	Number	An int representing the total number of 4- and 5-star ratings. This is null for Android apps from Google Play.
negative	Number	An int representing the total number of 1- and 2-star ratings. This is null for Android apps from Google Play.
neutral	Number	An int representing the total number of 3-star ratings. This is null for Android apps from Google Play.
new_positive	Number	An int representing the number of 4- and 5-star ratings received in the selected period. This is null for Android apps from Google Play.
new_negative	Number	An int representing the number of 1- and 2-star ratings received in the selected period. This is null for Android apps from Google Play.
new_neutral	Number	An int representing the number of 3-star ratings received in the selected period. This is null for Android apps from Google Play.
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 is 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 is 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 is 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 is 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 is 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"
}

Here’s the response for an Android app from Google Play:

// 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 set a granularity other than daily, we round this down to the nearest period. Defaults to the first date we have data for.
end_date	Date	(yyyy-MM-dd) Date, inclusive, to stop reporting. If you set a granularity other than daily, we round this up to the nearest period. Defaults to yesterday.
group_by	List	One or more pivots separated by a comma (,). Available pivots: product, country, date.
products	List	(productId, productId1, productId2, …) Products to include in the response. Defaults to all active products in the account.
countries	List	(isoCode1, isoCode2, …) Countries to limit the report to. See /data/countries for codes. Defaults to all countries.
format	String	Output format: JSON or CSV. Defaults to JSON. Note: With format=csv, we don’t fully serialize nested objects (like the product in /sales/products/…). You get only a reference to each one, to cut down on repetition.

Note

If group_by includes date and you don’t set start_date or end_date, the report covers the past 30 days.

Response

The shape of the response depends on group_by. Whatever the grouping, the innermost objects match the ungrouped response above.

Here are a few examples:

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