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 1,000. A filter value of 100 will only include records where the rank position is better than 100 (ex. 25). When blank this defaults to 400.

Not all stores/categories can go as deep as 1,000.

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/2017-06-05/2017-06-07/?countries=gb;us

{
  "start_date": "2017-06-05T00:00:00",
  "end_date": "2017-06-07T00:00:00",
  "dates": [
    "2017-06-05T00:00:00",
    "2017-06-06T00:00:00",
    "2017-06-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,
        179,
        null
      ],
      "deltas": [
        -3,
        2,
        null
      ]
    },
    . . . 
}

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 – 1,000. This defaults to 400.

Not all stores/categories can go as deep as 1,000.

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": "2017-06-07T16: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": "2016-12-01T00:00:00-05:00",
      "added_date": "2016-12-01T02:21:09-05:00",
      "updated_date": "2017-06-04T03:00:00-04:00",
      "version": "2.3.4",
      "source": null,
      "type": "app",
      "devices": [
        "Handheld"
      ],
      "price": {
        "currency": "USD",
        "price": "0.00"
      }
    },
 ...
}