Reviews | App Store API

The /reviews resource provides access to app reviews from any platform we support, with a variety of filters, as well as review counts and breakdowns.

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 Reviews

Request

GET /reviews?{filters}

Arguments

Argument	Type	Description
q		Only return reviews matching this string
products		One or more product ids separated by a comma. Defaults to all products in the account.
countries		One or more country iso 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 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 on or after this date will be returned.
end		A date in format yyyy-mm-dd. Only reviews that were created on or before this date will be returned.

This route uses paging. This means that requests that results in lots of reviews will require making additional requests to retrieve all results. The number of review retrieved in a single request can be specified with the count parameter. The response will indicate how many reviews are available and how many pages are available. Change the page value to continue getting more pages of results.

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	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 a translation language has been provided this will hold the translated review.
review	String	The full review. If a translation language has been provided this will hold the translated review.
original_title	String	If a translation language has been provided this will hold the original title before translation. Otherwise this field will be null.
original_review	String	If a translation language has been provided this will hold the original review before translation. Otherwise this field will be null.
author	String	The name of the author that left this review.
version	String	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.
date	Date	Date the review was left on the store.
stars	Number	Number of stars the author left for the app.
iso	String	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	Number	The ID of the product this review belongs to.
has_response	Boolean	Wether the developer responded to this review. Notes: Only responses submitted through Appfigures will be registered. Responding through App Store Connect or Google Play directly will not be reflected at this time. That may change in the future. Reviews for apps you don’t own will always results in a `false` value.
predicted_langs	List	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==",
        "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		Only return reviews matching this string
products		One or more product ids separated by a comma. Defaults to all products in the account.
countries		One or more country iso 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 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 on or after this date will be returned.
end		A date in format yyyy-mm-dd. Only reviews that were created on or before this date will be returned.

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.

Response

Field	Description
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

Getting Replies

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 for the review to get replies to

Response

Field	Description
content	The body of the response, UTF8 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 that submitted the reply, including the user’s ID and name. Additional information about the user can be retrieved using the /users route

Example Request

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

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 for the review to reply to
content	String	The full response string you want posted to the store. The content string can contain emoji

Example Request

// POST /reviews/41308033046LxPasT0qn1FCl7n8jsznb1A/response

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