v1.1 to v2 Migration Guide

While there are many small changes to various routes when migrating from v1.1 to v2 of our API, you’ll need to look out for four primary things:

  1. New authentication requirements
  2. product_ids have changed
  3. /iads is now named /reports/ads
  4. /reviews route has changed
  5. /ranks route’s representation has changed radically.

You can look at ‘what’s new in v2‘ to see everything that’s changed between the two versions, here we’ll just discuss the biggest breaking changes and how to work around them.

New Authentication Requirements

API v2 now supports OAuth 1.0a and requires an API key for all requests. You can generate an API key here. If your implementation only needs access to your account, you can continue to use HTTP Auth by adding the X-Client-Key header to your requests. If your implementation needs to support multiple accounts take a look at the authentication guide for more details.


In v1.1 each app or inapp had an identifier specific only to your account. Now all apps and inapps have a global Appfigures identifier. We did this so that private and public data can use the same set of IDs, even when you are looking for ranks, reviews, and other public data of apps that may not be in your account.

To aid in migration we’ve added a few new fields to the product representation in v1.1: new_inapp_product_ids, new_product_id, new_parent_product_id. These show the v2 ids of the product and its parent respectively.

There is also an expanded set of resources for lookup of products, documented here.


We’ve replaced /iads with /reports/ads which has the same power and flexibility of the /reports/sales route. You can now break down arbitrarily by product, store, date, or country. Representations have stayed largely the same.


The reviews resource has received a major overhaul. Rather than baking products and countries into the url, now the resource represents all of the reviews in your account (or the given products) filterable by country, stars, author, and dates. Pagination is now baked into the representation in a more consistent fashion.

The representation of a review has stayed largely the same, but the envelope has changed, you can take a look by comparing these: v2 vs. v1.1.

Old Request: /v1.1/reviews/3454/us;gb/0/

New Request: /v2/reviews?products=3454&countries=us;gb&page=0


The representation of the ranks resource has also received a major overhaul. The v1.1 representaiton was ‘row oriented’. Each entry represented a particular rank at a particular instant. This made for a lot of duplication in the rows, as products and categories were repeated over and over again hour per hour.

The new representation is column-oriented. For each product/category there are arrays of corresponding positions, and deltas representing each timestamp in the request. You can check it out here.