Reviews

The /reviews resource gives you app reviews from every store we support, plus review counts and breakdowns. You can filter reviews by app, country, version, stars, author and more.

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 Reviews

Request

GET /reviews?{filters}

Arguments

Argument	Type	Description
q		Return only reviews that match this string.
products		One or more product IDs separated by a comma. Defaults to all products in the account.
countries		One or more ISO country codes separated by a comma. Defaults to all countries.
page		Page number. Defaults to 1. Max is 500.
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 the language to translate reviews into. Get the list of supported languages from /data/languages. By default, we don’t translate reviews.
author		Name of an author to filter reviews by.
versions		One or more version numbers separated by a comma. Ex. 1.1,1.2 returns reviews for versions 1.1 and 1.2 of the app(s). Defaults to all versions.
stars		One or more star counts separated by a comma. Ex. 1,5 returns only 1- and 5-star reviews. Defaults to all star ratings.
sort		How to sort the reviews. Possible values: country, stars, date. Sorting is ascending. To reverse it, prepend a - to the value. Ex. -date returns the newest reviews first. Defaults to -date.
start		A date in format yyyy-mm-dd. Returns only reviews created on or after this date.
end		A date in format yyyy-mm-dd. Returns only reviews created on or before this date.

Note

This route uses paging. If a request matches lots of reviews, you’ll need more than one request to get them all. Set how many reviews you get per request with count. The response tells you how many reviews and pages are available. Change page to get the next page.

Response

Field	Type	Description
total	Number	The total number of reviews that match this request.
pages	Number	The total number of pages for the given count.
this_page	Number	The current page.
reviews	List<Review>	An array with review objects for the requested page. More details are available in the table below.

Review

Field	Type	Description
id	String	A unique ID for this review.
title	String	The title of the review. If you set a translation language, this holds the translated title.
review	String	The full review. If you set a translation language, this holds the translated review.
original_title	String	If you set a translation language, this holds the original title. Otherwise it’s null.
original_review	String	If you set a translation language, this holds the original review. Otherwise it’s null.
author	String	The name of the author who left this review.
version	String	The version of the app this review is for. Not all stores include the app version in reviews. For those apps, this is null.
date	Date	The date the review was left on the store.
stars	Number	The number of stars the author gave the app.
iso	String	The country code where we found this review. Note: ISO is available only for iOS and Mac apps. Google Play doesn’t report countries. It reports the language of the user’s device instead. That’s why 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	Number	The ID of the product this review belongs to.
has_response	Boolean	Whether the developer responded to this review. Note: We count only responses sent through Appfigures. Responses you post directly in App Store Connect or Google Play won’t show up here. Reviews for apps you don’t own always return false.
predicted_langs	List	An array of one or more languages our algorithm detected in this review.

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==",
        "has_response": false
    }, {
        "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==",
        "has_response": true
    }, {
        "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==",
        "has_response": false
    }, {
        "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==",
        "has_response": true
     }]
}

Getting Review Counts

Request

GET /reviews/count?{filters}

Arguments

Argument	Type	Description
q		Return only reviews that match this string.
products		One or more product IDs separated by a comma. Defaults to all products in the account.
countries		One or more ISO country codes separated by a comma. Defaults to all countries.
page		Page number. Defaults to 1. Max is 500.
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 the language to translate reviews into. Get the list of supported languages from /data/languages. By default, we don’t translate reviews.
author		Name of an author to filter reviews by.
versions		One or more version numbers separated by a comma. Ex. 1.1,1.2 returns reviews for versions 1.1 and 1.2 of the app(s). Defaults to all versions.
stars		One or more star counts separated by a comma. Ex. 1,5 returns only 1- and 5-star reviews. Defaults to all star ratings.
sort		How to sort the reviews. Possible values: country, stars, date. Sorting is ascending. To reverse it, prepend a - to the value. Ex. -date returns the newest reviews first. Defaults to -date.
start		A date in format yyyy-mm-dd. Returns only reviews created on or after this date.
end		A date in format yyyy-mm-dd. Returns only reviews created on or before this date.

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.

Response

Field	Description
stars	Object of star values mapped to counts.
versions	Object of version values mapped to counts.
countries	Object of ISO codes mapped to counts.
products	Object of product_ids mapped to counts.

Getting Replies

Caution

This route is available on select plans and may also require a commercial license. Contact us for more details.

Request

GET /reviews/{review_id}/response

Arguments

Argument	Type	Description
review_id	String	The Appfigures-assigned ID of the review to get replies for.

Response

Field	Description
content	The body of the response, UTF-8 encoded with support for emojis.
timestamp	The date and time this reply was submitted.
external_account	Information about the linked account this reply was submitted through.
user	Information about the Appfigures user who submitted the reply, including the user’s ID and name. Get more details about the user from the /users route.

Example Response

// GET /reviews/41318011046LoNasTPqn1FQlLn8jsznb1A/response

{
  "content": "😃 Glad you like the app, and thank you for the suggestion. It's already on our roadmap.",
  "timestamp": "2020-03-29T17:27:01",
  "external_account": {
    "storfront_id": "apple:ios",
    "type": "itunes_connect",
    "name": "dev@example.com"
  },
  "user": {
    "id": 123456,
    "name": "Appfigures User"
  }
}

Replying to a Review

Caution

This route is available on select plans and may also require a commercial license. Contact us for more details.

Request

POST /reviews/{review_id}/response

Arguments

Argument	Type	Description
review_id	String	The Appfigures-assigned ID of the review to reply to.
content	String	The full reply you want posted to the store. It can include emoji.

Example Request

// POST /reviews/41308033046LxPasT0qn1FCl7n8jsznb1A/response

{
  "content": "Hey! Thank you 😄 We're glad to hear you're enjoying the game! Play on!"
}

Response

This endpoint returns HTTP 202 Accepted instead of the usual 200 OK. We post replies asynchronously, so they can take some time to appear.

A 202 response means we received your reply and queued it. There’s nothing else you need to do. The reply appears on the store once we’ve processed it. Replying won’t remove the review or change its rating.