Reviews

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!"
}