Ranks

Ranks show where your apps stand in the app stores. You can get them from the API in two ways:

Basic reports show ranks across the countries and apps you select.
Snapshot reports show the full standings for one country and category.

Generating a Ranks Report

Request

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

Arguments

Field	Type	Description
product_ids	Array	One or more product_ids to get ranks for. Separate multiple product_ids with a comma (,). You need the Public Data API add-on to access data for products your account doesn’t own. On a free account, you need it even for products in your account.
granularity	String	Data granularity: “hourly” or “daily”.
start_date	Date	Day to start the report on, in format yyyy-MM-dd.
end_date	Date	Day to end the report on, in format yyyy-MM-dd.
countries	Array	One or more countries to get ranks from. Separate multiple ISO codes with a semicolon (;). Defaults to US. See /data/countries for codes.
tz	String	(user \| utc \| est) The time zone to use. Defaults to est.
filter	Number	Limit results to ranks in the top N, where N is between 1 and 1,000. A filter of 100 returns only records with a rank better than 100 (ex. 25). Defaults to 400. Not all stores and categories go as deep as 1,000.
format	String	Output format: json or csv. Defaults to json.

Response

This route returns a container with request metadata (start and end dates) and the ranks for each series. A series is one product’s rank over time in one country and category.

Container Representation:

Field	Type	Description
start_date	Date	The start date of the report.
end_date	Date	The end date of the report.
dates	Array	The dates that the series positions and deltas below map to.
data	Array	List of series (see below). Each series has a category, country and product, plus arrays of positions and deltas that match the dates above.

Series Representation:

Field	Type	Description
country	String	ISO code of the country this series is for.
category	Category	Representation of the category this series is for.
product_id	Number	The product that this series is for.
positions		List of rank positions (1-indexed) that match the dates above.
deltas		List of rank changes that match the dates above. The delta is always from the prior hour, even if the granularity is daily.

Example Response

// GET /ranks/41046955155/daily/2019-06-05/2019-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