/ratings resource provides access to an app’s standalone ratings over time.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 Ratings
### Request
GET /ratings?{filters}
### Arguments
_All filters are optional. If a filter isn’t specified the default value for that filter will be used._
- 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 will be broken down by day, product, and country. Passing a group_by will change the breakdown. Possible values are: date, region, product. Only one group_by is allowed.
- 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, all-time ratings are returned. Set all_time to false to get the current version’s ratings.
Note: No other store supports current version ratings, so setting all_time to false with non-Apple apps will result in an empty response.
### Response
| 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, while Google does not break them down at all. Non-Android apps will have a 2-letter country code. Android apps will have “L:en” (the same language notation we use for reviews from Google Play). |
| date | The date for this rating snapshot. |
| stars | An array containing the total number of 1/2/3/4/5 ratings. The array will always contain five numbers with the first being the number of 1 star ratings and last being the number of of 5 star ratings.
Note: The ratings returned are a snapshot of the total ratings for the app for the specific day. There’s no need to sum up ratings over time. |
### 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
We collect ratings data for hundreds of thousands of apps every day. If you’re a member, your apps are covered, if you’re using the Public Data API with apps you don’t own however, your initial request might not result in any data.
The Public Data API actively keeps track of the most active/popular apps as well as apps requested by members. This means that if you’re requesting an app that isn’t active/popular, the request will return and empty array. In the background, we’ll update the app so your next request should have data. After the first update, we’ll be tracking the app daily.
Initial updates usually take minutes to complete, but in some cases may take as long as an hour so you may need to retry a few times.