Reviews

The /reviews resource provides access to reviews with a variety of filters, as well as review count breakdowns.
Scope: All of the resources in this route require read access in the public scope (public:read).

Getting Reviews

Request

GET /reviews?{filters}

Arguments

All filters are optional. If a filter isn’t specified the default value for that filter will be used.

q
Only return reviews matching this string


products
One or more product ids separated by a comma. Defaults to all products in the account.
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.


countries
One or more country iso codes separated by a comma. Defaults to all countries.


page
Page number. Defaults to 1.


count
The number of reviews to return. Any number between 1 and 500 is valid. Defaults to 25 reviews per request.


lang
Short code of language to translate reviews into. A complete list of supported languages can be retrieved from /data/languages. By default reviews will not get translated.


author
Name of an author to filter reviews by.


versions
One of more version numbers separated by a comma. Ex. 1.1,1.2 will retrieve any reviews for versions 1.1 and 1.2 of the app(s). By default reviews for all versions will be returned.


stars
One of more star counts separated by a comma. Ex. 1,5 will retrieve any reviews that have 1 or 5 star ratings only. By default reviews with any star rating will be returned.


sort
How to sort the resulting reviews. Possible values: country, stars, date. By default the sort order is ascending, to reverse the order prepend a – to the value. Ex: -date will return newest reviews first. Defaults to -date.


start
A date in format yyyy-mm-dd. Only reviews that were created after this date will be returned.


end
A date in format yyyy-mm-dd. Only reviews that were created before this date will be returned.


Response

total The total number of reviews that match this request.
pages The total number of pages for the given count.
this_page The current page.
reviews An array with review objects for the requested page. More details are available in the table below.
Review
id A unique ID for this review.
title The title of the review. If a translation language has been provided this will hold the translated review.
review The full review. If a translation language has been provided this will hold the translated review.
original_title If a translation language has been provided this will hold the original title before translation. Otherwise this field will be null.
original_review If a translation language has been provided this will hold the original review before translation. Otherwise this field will be null.
author The name of the author that left this review.
version The version of the app this review is for. Not all app stores support app version in reviews. Reviews for those apps will return null for the version.

Unsupported app stores include iOS and Mac.
date Date the review was left on the store.
stars Number of stars the author left for the app.
iso The country code where this review was observed.

Note: ISO is only available for iOS and Mac apps at this time. Google Play does not support the concept of countries but rather reports the language the user’s device is set to. For that reason all reviews from Google Play will have their language set to ZZ.

The language of the reviews for those apps will be available as a separate key in a future update.
product The ID of the product this review belongs to.
predicted_langs An array consisting of one or more languages that our algorithm interpreted this review as being written in.

Example Response

// GET /reviews?stars=5&count=4&products=56556

{
    "total": 140,
    "pages": 28,
    "this_page": 1,
    "reviews": [{
        "author": "DeveloperToDeveloper",
        "title": "Just Spectacular",
        "review": "Finally able to remove the ads! The description is hilarious!! Thanks!!!",
        "original_title": null,
        "original_review": null,
        "stars": "5.00",
        "iso": "US",
        "version": "1.2",
        "date": "2017-05-19T17:05:00",
        "product": 6567539,
        "weight": 0,
        "id": "5561747L7xnbsMRu8UbPvy7A71Dv6A=="
    }, {
        "author": null,
        "title": "Boat finder",
        "review": "Very good app for my use, regrefully does not Search vessel by name.",
        "original_title": null,
        "original_review": null,
        "stars": "5.00",
        "iso": "US",
        "version": "1.32",
        "date": "2017-05-10T21:15:56",
        "product": 5561747,
        "weight": 0,
        "id": "008bVy7L7xnbsMRu8UbPvy7xx1Dv6A=="
    }, {
        "author": "Dito",
        "title": "Boat finder",
        "review": "Very good app for my use, regrefully does not Search vessel by name.",
        "original_title": null,
        "original_review": null,
        "stars": "5.00",
        "iso": "US",
        "version": "1.32",
        "date": "2017-05-10T21:15:56",
        "product": 5561747,
        "weight": 0,
        "id": "5561747L7xhfgdbs09oyvy7A71Dv6A=="
    }, {
        "author": "KTM SX",
        "title": "À quand le deuxième épisode",
        "review": "Super une maj pour d'autre decore et autre",
        "original_title": null,
        "original_review": null,
        "stars": "5.00",
        "iso": "FR",
        "version": "1.2",
        "date": "2017-04-19T13:58:00",
        "product": 5858288,
        "weight": 0,
        "id": "5561747L7xnbsMRu8UbP9s9s754gdt=="
     }]
}

Getting Review Counts

Request

GET /reviews/count?{filters}

Arguments

All filters are optional. If a filter isn’t specified the default value for that filter will be used.

q
Only count reviews matching this string


products
One or more product ids separated by a comma. Defaults to all products in the account.
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.


countries
One or more country iso codes separated by a comma. Defaults to all countries.


author
Name of an author to filter reviews by.


versions
One of more version numbers separated by a comma. Ex. 1.1,1.2 will retrieve any reviews for versions 1.1 and 1.2 of the app(s). By default reviews for all versions will be returned.


stars
One of more star counts separated by a comma. Ex. 1,5 will retrieve any reviews that have 1 or 5 star ratings only. By default reviews with any star rating will be returned.


start
A date in format yyyy-mm-dd. Only reviews that were created after this date will be returned.


end
A date in format yyyy-mm-dd. Only reviews that were created before this date will be returned.


Response

stars Object of star values mapped to counts
versions Object ofversion values mapped to counts
countries Object of ISO codes mapped to counts
products Object of product_ids mapped to counts

Example Response

// GET /reviews/count?q=best&versions=1.0

{
  "stars": {
    "5": 5,
    "4": 1
  },
  "versions": {
    "1.0": 6
  },
  "countries": {
    "US": 4,
    "RO": 2
  },
  "products": {
    "5923605": 5,
    "5858288": 1
  }
}
  • msaffitz

    How are changes to reviews handled? For example, if someone leave a review in the Play store for an app and then goes change changes their review– will this appear as a new review or will the existing review be updated and maintain the same ID? If it’s updated, is there a way to get the review history for a given ID?

  • Frank Quiz

    Hi,

    I get error response #429 about 90% of the times during my requests, saying I’ve exceeded my rate limit even though i’m not even close to doing so. Seems to be specific to translating the reviews, as I can iterate over many pages with count=500 on each, if I don’t request translations. I have tried both minimal count values and a wait time between requesting a new page, but it still only works on some occasions. What do I do?

    • Frank Quiz

      {u’status’: 429, u’message’: u’Error Translating (Exceeded Rate Limit)’, u’additional’: u”, u’reference’: u”}

      • appfigures

        We have an additional hard limit on the number of translations that’s separate from the daily request limit.

        If you’d like the limit increased please get in touch directly through the site.

  • ivetam

    When I try to report on more then one products (&products=,,) it only returns reviews for the first ID

  • Alina GHERMAN

    Hello,

    For some reason, for the android application I cannot manage to get all countries.

    In fact I think there is a problem with the countries filter for android.

    For a google application there are different comments in function of the language and the page google without the language filter (without hl=fr in the example) is not returning all comments . https://play.google.com/store/apps/details?id=MYAPPID&hl=fr

    The appfigure API is doing the same, without the countries filter I do not get all the comments (all over the countries).

    However, even if I add the country FR to get (iso code), I cannot manage to get all comments that I have in google play with language &hl=fr

    Could you please help?

    Thank you!

    • Alina GHERMAN

      P.S. I have the same problem in the appfigure interface( I cannot mange to have all the reviews)

  • Yala

    Hi,

    I’m trying to get the reviews count till a date using end, for example: reviews/count?products=6756611&end=2013-11-09

    and I got this error:

    { “status”: 500, “message”: “Oops. Server Error. Use the reference number below to get help.”, “additional”: “Reference: 0922403a-c03f-4eb5-b54e-0a7d68eaeb47”, “reference”: “0922403a-c03f-4eb5-b54e-0a7d68eaeb47” }

    if I change “end” to “start” it returns fine.

  • EdmondGZL

    Hi, For some reason I get only “ZZ” iso code for google-play app:

    { u ‘product’ : XXXXXXX, u ‘original_review’ : u ‘Cool’, u ‘predicted_langs’ : [u ‘en’, u ‘nl’], u ‘weight’ : 0, u ‘title’ : u ‘Lover’, u ‘review’ : u ‘Cool’, u ‘author’ : u ‘Niyah Williams’, u ‘original_title’ : u ‘Lover’, u ‘version’ : u ‘2.3.1’, u ‘iso’ : u ‘ZZ’, u ‘stars’ : u ‘2.00’, u ‘date’ : u ‘2015-03-25T21:26:18’, u ‘id’ : u ‘5563616L+54yLadWtEC9wjHfHollFg==’ }

    Why is that? No such problem for with iOS data.

    Thanks, Edmond

    • appfigures

      Google doesn’t have the concept of countries in its store but instead uses the device’s language.

      We updated the documentation to explain how this works.

      • Monsta man

        Hi! It actually doesn’t clearly explains. Quote: Google Play does not support the concept of countries but rather reports the language the user’s device is set to.

        Could you report the language of the user’s device? Or we rather should use predicted_langs ?

  • Pedro Nóbrega da Costa

    Hi, im trying to start using and undestating the API

    why is that i can get comments with the id from the sample example with:

    …/reviews?products=212135374&client_key={my key}

    but not with other ids (such as 44823544)? (yes that id exists) as you can see here: …/products/44823544?client_key={my key}

    i always get 0 reviews, any idea why?

    • appfigures

      Do you mind getting in touch with support about this?

  • appstickdev

    getting for reviews url: https://api.appfigures.com/v2/reviews

    {

    “total”: 0,

    “pages”: 0,

    “this_page”: 1,

    “reviews”: []

    }

  • appstickdev

    Using python I do get products (so connecting seems to be OK)

    But I cannot get reviews :

    1) using your example:

    /reviews?stars=5&count=4&products=56556

    I receive 400 invalid

    2) using /reviews?count=100&&products=39008614251,39746718020,39861842927,40212303831,40335889295&start=2014-01-01&end=2015-02-01

    I get 500, ref: 070c9322-226e-4c82-9346-36416314c4a1

    I must be doing something wrong, what is it? THANKS in advance

    • appstickdev

      The crush is due to a typo of double “&&” in the URL line

  • MiSter

    Would be great to know from which store (iOS, Android) the review comes.

    • Ariel Michaeli

      You can get that by looking at the product.

    • appfigures

      You can get that by looking at the product.

      • MiSter

        Not while using the RSS feed.

        • appfigures

          The RSS feed isn’t actually a part of the API but rather a feature in the site, which is why it doesn’t follow the API documentation.

          If you need this type of access we recommend using the API directly. We don’t support RSS format but the JSON is clean and really easy to process.

          • MiSter

            Understood. But I am using the RSS feed to transfer data automatically with Zapier. So no way to access additional data.

  • Jim

    Is there a way to get a dump of all pages?

    ……&page=1-1XXX

    • Ariel Michaeli

      That’s not possible because it could result in a massive response object that would most likely time out or crash the parser.

      Instead, we made it possible to ask for more reviews per page by adding

      &count=[value between 0 and 500]
      to your url.

    • appfigures

      That’s not possible because it could result in a massive response object that would most likely time out or crash the parser.

      Instead, we made it possible to ask for more reviews per page by adding

      &count=[value between 0 and 500]
      to your url.

  • Andy

    Hi there. One question: How do I get all pages out of the reviews? By default he just gives me one page.

    • Ariel Michaeli

      Every request returns the total number of pages. To get them all you’ll need to iterate over them and add

      &page=[page]
      to your url.

    • appfigures

      Every request returns the total number of pages. To get them all you’ll need to iterate over them and add

      &page=[page]
      to your url.

  • Sean White

    Since ratings can be independent of reviews, it would be nice if this endpoint could also return the number of ratings in the response as well as a breakdown.

    • appfigures

      We’ll be adding a new route for ratings in the near future.

      • Artiom Kreimer

        Any update on when ratings will be available?

        • appfigures

          We’re in the process of rolling it out. Keep an eye on the blog for the actual release.

          • Jeff Brown

            Any luck on this?

          • Artiom Kreimer

            Any progress on this one?

        • Dominik Deobald

          For everyone waiting: The /ratings endpoint is now available. It’s just not documented, yet. I tried it with the same parameters as this one, and it seems to work as expected.

        • appfigures

          We’ve rolled out the /ratings route. Check out the documentation: http://docs.appfigures.com/api/reference/v2/ratings

  • Sean White

    There is a typo documenting the “page” parameter. It says “Zero-based page number. Defaults to 1.”. It’s definitely not zero-based in that case 🙂 I tested just to see and the API returns an error.

    • appfigures

      You’re right. Good catch! We fixed the documentation.