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

Field Type Description
product_ids Array One or more product_ids to get ranks for. Separate multiple product_ids with a comma (,).

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 String Data granularity, either “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 (;). If no country iso is specified ‘US’ will be used. Countries can be found here: /data/countries
tz String (user | utc | est) specifies which timezone to use, defaults to est
filter Number 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 String 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:

Field Type Description
start_date Date The start date of the report
end_date Date The end date of the report
dates Array Array of dates that are mapped against the series position/delta data below
data Array List of series entries(see 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:

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 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/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

Request

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

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

Arguments

Field Type Description
time string “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 please contact us.

country String The iso code of the country you’d like to get a snapshot for. Countries can be found here: /data/countries
category String The category_id of the category to get a snapshot for. Categories can be found here: /data/categories
subcategory String The sub-category to get a snapshot for. Options: “free”, “paid”, “topgrossing”.
count Number 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 Number 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:

Field Type Description
category Category A representation of the category
country string The iso code of the country of the app store. The full name of the country is available in /data/countries.
timestamp Date The time that the snapshot was taken
page_count Number The number of results in this representation
page_start Number The index this page starts on.
total_count Number The total number of entries in this snapshot.
entries Array The top apps, in order

Example Response

GET /ranks/snapshots/current/us/71/free?count=1000

{
  "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"
      }
    },
 ...
}