Skip to content

Ratings

The /ratings resource gives you an app’s standalone ratings over time.

Getting Ratings

Section titled “Getting Ratings”

Request

Section titled “Request”

GET /ratings?{filters}

Arguments

Section titled “Arguments”

All filters are optional. If you leave one out, we use its default.

Argument Description
products One or more product IDs separated by a comma (,). Defaults to all active products in the account.
countries One or more 2-letter country codes separated by a comma. Defaults to the US.
group_by By default, ratings are broken down by day, product and country. Pass a group_by to change the breakdown. Possible values: date, region, product. You can pass only one group_by.
start_date A date in format yyyy-mm-dd. Only days after this date will be returned.
end_date A date in format yyyy-mm-dd. Only days before this date will be returned.
all_time Apple breaks ratings down into all-time and current version. By default, you get all-time ratings. Set all_time to false to get the current version’s ratings.

Note: No other store has current-version ratings, so setting all_time to false for non-Apple apps returns an empty response.

Response

Section titled “Response”
Field Description
product A unique Appfigures-assigned ID for this app. You can look up the product ID using the /products route.
region The country or language for this rating snapshot.

Note: Apple, Amazon and Microsoft break down ratings by country. Google doesn’t break them down at all. Non-Android apps have a 2-letter country code. Android apps have “L:en” (the same language notation we use for reviews from Google Play).
date The date for this rating snapshot.
stars An array of the total number of 1/2/3/4/5 ratings. It always has five numbers: the first is the number of 1-star ratings and the last is the number of 5-star ratings.

Note: Each entry is a snapshot of the app’s total ratings on that day. Don’t sum ratings over time.

Example Response

Section titled “Example Response”
// GET /ratings


[
  {
    "product": 58582881,
    "region": "US",
    "date": "2017-06-07T00:00:00",
    "stars": [
      316,
      277,
      332,
      188,
      342
    ]
  },
  {
    "product": 2091143,
    "region": "US",
    "date": "2017-06-08T00:00:00",
    "stars": [
      316,
      277,
      332,
      188,
      342
    ]
  },
  ...
]

Important Note

Section titled “Important Note”

We collect ratings for hundreds of thousands of apps every day. If you’re a member, your apps are covered. If you use the Public Data API for apps you don’t own, your first request might not return any data.

The Public Data API tracks the most active and popular apps, plus apps members request. If you request an app outside that set, you’ll get an empty array. We’ll update the app in the background, so your next request should have data. After that first update, we track the app daily.

The first update usually takes minutes but can take up to an hour, so you may need to retry a few times.