Ranks

Ranks show your standings in the app store, there are a two different ways to get that data from the API.
  • Basic reports show you ranks across selected countries and apps
  • Snapshot reports let you see the full standings of a particular country and category.
Scope: All of the resources in this route require read access in the public scope (public:read).

Generating a ranks report

Request

GET /ranks/{product_ids}/{granularity}/{start_date}/{end_date}/?countries={countries}&filter={filter}&tz={tz}&format={format}

Arguments

product_ids REQUIRED
One or more product_ids to get ranks for. Separate multiple product_ids with a semicolon (;).


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.
granularity REQUIRED
Data granularity, either hourly or daily.


start_date REQUIRED
Day to start the report on in format: yyyy-MM-dd.


end_date REQUIRED
Day to end the report on in format: yyyy-MM-dd.


countries
One or more countries to get ranks from. Separate multiple iso codes with a semicolon (;). If no country iso is specified ‘US’ will be used. Countries can be found here: /data/countries


tz
(user | utc | est) specifies which timezone to use, defaults to est


filter
Limit results to ranks in the top N with N being a number between 1 and 400. A filter value of 100 will only show records where the rank position is better than 100 (ex. 25). When blank this defaults to 400.


format
Output format: json or csv. Defaults to json.


Response

This route returns a container with request metadata (start, end dates) and an inner containing the ranks for each series. A series represents a particular product’s movement through ranks over time with respect to a given country and category.

Container Representation

start_date The start date of the report
end_date The end date of the report
dates Array of dates that are mapped against the series position/delta data below
data List of series entries(look below). Each series has a category, country, and product as well as the positions and deltas in array form that correspond to the above dates.

Series Representation

country ISO code of the country this series is for.
category Representation of the category this series is for.
product_id The product that this series is for.
positions List of rank positions (1-indexed) that map with the dates above
deltas List of rank changes that map with the dates above. The delta is always fromt the prior hour even if the granularity is daily

Example Response

// GET /ranks/520459/daily/2010-07-05/2010-07-07/?countries=gb;us


{
  "start_date": "2010-07-05T00:00:00",
  "end_date": "2010-07-07T00:00:00",
  "dates": [
    "2010-07-05T00:00:00",
    "2010-07-06T00:00:00",
    "2010-07-07T00:00:00"
  ],
  "data": [
    {
      "country": "US",
      "category": {
        "store": "apple",
        "store_id": 1,
        "device": "handheld",
        "device_id": 1,
        "name": "Games/Family",
        "subtype": "paid",
        "id": 7009,
        "parent_id": 6014
      },
      "product_id": 5923605,
      "positions": [
        186, // for 2010-07-05
        179, // for 2010-07-06
        null  // for 2010-07-07 (not ranked at all)
      ],
      "deltas": [
        -3,  //change from 2010-07-04 23:00:00
        2,   //change from 2010-07-05 23:00:00
        null   //change from 2010-07-06 23:00:00
      ]
    },
    . . .
}

Generating a ranks snapshot for a category

Request

GET /ranks/snapshots/{time}/{country}/{category}/{subcategory}/?top={top}

The Public Data API add-on is required for this route.

Arguments

time REQUIRED
“current” to get the most recent snapshot or a date with an hour that’s within the last 24 hours in format: yyyy-mm-ddTHH.

Important: Requests for dates/times not within the last 24 hours will result in a 404 response. If you need snapshots for earlier dates check out Appbase.


country REQUIRED
The iso code of the country you’d like to get a snapshot for. Countries can be found here: /data/countries


category REQUIRED
The category_id of the category to get a snapshot for. Categories can be found here: /data/categories


subcategory REQUIRED
The sub-category to get a snapshot for. Options: “free”, “paid”, “topgrossing”.


count
Number of results to return between 1 – 400. This defaults to 400.


start
Result index to start returning results from. Can be used with count to page through a larger resultset.


Response

The response is a JSON object with the following properties:

category Representation of the category. See here for format: /data/categories
country The iso code of the country of the app store. The full name of the country is available in /data/countries.
timestamp The time that the snapshot was taken
page_count The number of results in this representation
page_start The index this page starts on.
total_count The total number of entries in this snapshot.
entries An array of product representations in order of ranking. The index + 1 is equivalent to the rank count unless start is given and nonzero, then the index + start + 1 is equivalent to the rank.

Example Response

// GET /ranks/snapshots/current/us/71/free?count=10
{
  "page_count": 10,
  "page_start": 0,
  "total_count": 400,
  "country": "US",
  "category": {
    "store": "google_play",
    "store_id": 2,
    "device": "Handheld",
    "device_id": 1,
    "name": "Tools",
    "subtype": "Free",
    "id": 71
  },
  "timestamp": "2013-06-27T16:00:00",
  "entries": [
    {
      "id": 5545649,
      "name": "Brightest Flashlight Free™",
      "developer": "GoldenShores Technologies, LLC",
      "icon": "http://lh6.ggpht.com/oxdTH6PDCgkz-6TkodfJc6fK3-xFsz_voyqslO2blEbAP0pow8R32KlS4sTPWS4j3A",
      "vendor_identifier": "goldenshorestechnologies.brightestflashlight.free",
      "package_name": "goldenshorestechnologies.brightestflashlight.free",
      "store_id": 2,
      "store": "google_play",
      "release_date": "2000-01-02T00:00:00-05:00",
      "added_date": "2011-12-01T02:21:09-05:00",
      "updated_date": "2013-06-04T03:00:00-04:00",
      "version": "2.3.4",
      "source": null,
      "type": "app",
      "devices": [
        "Handheld"
      ],
      "price": {
        "currency": "USD",
        "price": "0.00"
      }
    },
 ...
}
  • William

    how can I get more than 400 results ? I want 2000.

    • appfigures

      There is no way to get more than 400 results. According to the stores, anything beyond 400 isn’t accurate and shouldn’t be used.

  • mittotnv

    Hi Team, The API can tracker keywords ranks on AppStore and Google play ?. Thanks

    • appfigures

      Not yet. Keep an eye on our blog to find out when that’s going to be available.

  • labaikie

    what is the max number of product_ids you can query at once?

    • appfigures

      We recommend no more than 5 at a time, however it’s possible to supply more. The requests may not complete in a timely manner however, depending on the amount of data being returned.

  • Harmeek Hans

    Do you guys have any python sample code to get ranks data?

    • https://appfigures.com/ Alex Quick

      Hi, you can look at http://docs.appfigures.com/code-samples. There are python samples for both HTTP Auth and oAuth. In each case the sample is making a request to /products/mine, but you can change that to /ranks/{product_ids}/{granularity}/{start_date}/{end_date} easily. Just remember that if you include any query string parameters to pass them in params kwarg so that the request gets signed correctly.

  • appstickdev

    your example above https://api.appfigures.com/v2/ranks/snapshots/current/us/71/free?count=10

    produces:

    {u’status’: 400, u’message’: u’Invalid signature’, u’additional’: u”, u’reference’: u”}

  • appstickdev

    always getting empty results, including your example {u’dates’: [], u’data’: [], u’start_date’: None, u’end_date’: None}

    using python code, I do get products info.

  • AK

    Regarding the ranks snapshot report, the time argument is defined as “[] a date with an hour that’s within the last 24 hours []” Does this mean only the past 24 hours’ worth of data is available?

    • appfigures

      Correct. At this time you can only go back 24 hours, but in the future we’re planning to enable going back further.

  • DARRYNK

    What timezone for the “time” variable is the snapshot report mapped against? For the rank, I can specify “user”, but as the snapshot rank doesn’t match the rank as shown in the reporting tool for a given time, I’m guessing it is “est” for the api? Can we have the same timezone variable added to the snapshot reports?

    • appfigures

      Both of your assumptions are correct:

      1. The timezone for snapshots is always EST. At this time there’s no way to change that, but we’ll explore making that possible in the future.

      2. The daily granularity is based on the rank for the app at midnight EST.

  • Kartik Subramanian

    How can I use this command (via my app) to check the rank report of the Facebook iOS app (NOTE: I dont own the Facebook iOS app 😉 )? I have authorized my app for public data access.

    As a background, I was able to use the /products route to access product info for the Facebook iOS app, using the command below (abbreviated), but am not sure how I could gather data about ranks/ratings/reviews of the same app

    curl -XGET -v ‘https://api.appfigures.com/v2/products/apple/284882215’ …

    • appfigures

      First, because you don’t own the app you’ll need to enabled the Public Data add-on (https://appfigures.com/account/addons/public-data).

      Once that’s enabled simply make a request to the /ranks endpoint with the product_id you got from the request to /products.

      If you run into any issues simply get in touch directly via email or live chat and we’d be happy to walk you through it.

  • Marc Schopper

    Why does pagination at the /ranks/snapshots API endpoint works different then at the /reviews endpoint? (page_start instead of this_page)

    • alexquick

      We thought that a row number rather than a page number may be more useful because the number of entries in a snapshot is pretty constant and low (normally 400). page_start is a row number while this_page is a page number.

      The justification doesn’t change the fact that it’s confusing and inconsistent. I’ll see what we can do to clear this up.

  • Sean White

    It would be nice if there was a way to get data for all countries without having to individually specify all of the country codes

    • appfigures

      Thanks for the suggestion Sean!

      • Michael Lakhia

        Do you plan on implementing his suggestion? I think this would be an almighty nice feature. It would also be nice to be able to retrieve more than 400 results 🙂

        • appfigures

          It’s something we’re exploring.

  • Guest

    @disqus_oyRY9eylD0:disqus it should be returning

    null

  • Sean White

    When rankings are presumably not available for a category and a particular date within a given date range, the API returns 0s for these rank positions. Is this the intended behaviour?

    • alexquick

      Good catch. This should now be resolved. Thanks Sean!

  • Tamara

    What’s the planned release date for V2.0?

    • appfigures

      Soon. We don’t have a concrete date at the moment as we’re still testing the new additions and modifications.

      • appfigures

        FYI – v2 has been officially released a few weeks ago 😉