Ratings

The /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 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.

  • Morten Nielsen

    Is it possible to get ratings by app version?

    • appfigures

      Unfortunately not at this time.

  • appfigures

    FYI – Ratings for some apps may take longer to become available. See the important note at the bottom of the documentation, and feel free to get in touch with support if you have any specific questions.

    /cc @disqus_B2o1OEMZWx:disqus @edwardeugenerichter:disqus @disqus_8XllZVXJq5:disqus @disqus_2tONyanVgU:disqus

  • Rossi

    Hi

    We are facing the same issue as Cheong with ratings data. We are able to pull ratings for Google Play but when we switch to Apple we get no data. The default is all products, as stated in the doco, but again we only get data for Google Play ratings.

    Can you please advise.

    Thanks

  • Tali Gillon

    Hi, does the api for ratings returns results that include the reviews? Sometimes users only give a stars rank without reviews.

    • appfigures

      Yes. The /ratings route returns the total number of ratings, which includes those with and without a text review.

  • Edward Eugene Richter

    I am also having the problem where Google Play rating data is being returned as blank. Any help would be greatly appreciated.

  • SFX

    Hi, I’m having the exact same issue as Cheong. Is there anything wrong with the API call? Changing to /sales gets me all the data for sales, but I receive nothing back for ratings.

  • Cheong

    Hi, I’m using the following to get my rating from Google Playstore but it only returns a blank [] https://api.appfigures.com/v2/ratings/?client_key=&products=41200978153 But if I change the products to point to Apple Store, it returns some values (a lot of blanks but some rating for the last two days). I know that the query above is correct as I can get download numbers by changing “/ratings” to “/sales”. Any tips? Thanks in advance. Kind regards, Cheong

    • Rossi

      Hi Cheong

      Have you had any luck with this.

      Thanks

  • Dominik Deobald

    From the data I get I assume that these ratings don’t include the star ratings from reviews? Or are there apps that don’t have current ratings data in your system?

    Reason for assumption: I have apps that have several reviews (including star ratings), but that do not have any ratings.

    An explanation of the “observed” attribute (@JTP mentioned that) would be nice, too. Maybe that means that there is no current data?

  • Matthew Schmohl

    so in order to query ratings for date $x one needs to require a start=$x-1 day and end=$x+1 day, then group by date and date date=$x? Seems extra difficult. I noticed numbers are buggy when querying where start=end=$x.

    • appfigures

      This route is somewhat experimental at this point and will see a few changes in the very near future.

  • JTP

    I see an ‘observed’ attribute returned that is always set to false, even if there’s valid data in the breakdown. Doesn’t seem to be documented. What does this indicate?

  • YZS

    I’ve turned on the Public Data Access Add-on, and found the correct AppFigures product ID, but my ‘breakdown’ always comes back as [0,0,0,0,0] no matter the product ID used. I’m accessing via my browser – what am I doing wrong?

    • appfigures

      It’s possible that the app(s) you’re querying are still in the process of updating. Contact us directly and we’ll be able to give you a better idea of what’s causing this response.

  • DARRYNK

    Why and how can there be a negative number of stars? For example, on one day, we got [0,-3,4,-1,-13]. Also, how can I verify the data from the api vs the data shown in the reports (just the ratings function)?

    • appfigures

      The array contains number of “new” ratings. Because a user can change their rating at any time, the total for any star group can actually decrease if users are constantly updating their ratings.

      As for a report – not at the moment. We’re working to add ratings data to the new reviews report and also as a more in-depth stand alone report.

      • SLI

        If I understand your explanations correctly, then, for an app, if its rating of 1 star is ‘-2’ on a particular day, it means some users have changed their mind and bumps up their ratings from 1 star to something better?