Ranks

v1.1 | v1.0

Generating a Ranks Report

Request

GET ranks/{productIds}/{granularity}/{startDate}/{endDate}/?countries={countries}&filter={filter}

Arguments

productIds
(productId | productId1;productId2;productIdN) the product(s) to get ranks data for.
The productId must belong to your account. To access public ranks through the API please contact us about our partner program.
granularity
(hourly | daily) whether to show daily or hourly data
startDate
(yyyy-MM-dd) Day to start the report on
endDate
(yyyy-MM-dd) Day to end the report on
countries (optional)
(isoCode | countryId | isoCode1;countryId1;isoCode2;isoCodeN) Countries to run report on. (default: US)
tz new (optional)
(user | utc | est) specifies which timezone to use, defaults to est
filter (optional)
(int[1-400], default 100) top N ranks. A filter value of 100 will only show records where the rank position is better than 100 (less than 100)
format new (optional)
Output format: json or csv. Defaults to json.

Response

The response is in the form {date=>[point1, point2] …} where a point is an array of [productId, countryId, categoryId, subcategory, rank_position, delta] (see table below).

Points will always be in the same order for each date, however they may not have the same index in each date as the app might fall below the filter threshold for the report

productId Id of the product
countryId ID of the country in the app store. Full name can come from /data/countries
categoryId ID of the category in the app store. Full name can come from /data/categories
subcategory A string representing the sub category. free | paid | topgrossing.
rank_position Rank for given timestamp
delta The change from the previous rank

Example Response

// GET /ranks/320459/daily/2010-07-05/2010-07-07/?countries=gb;us
 
{
    "07/07/2010 00:00:00": [
      [
        320459,
        143441,
        7009,
        "paid",
        175,
        10
      ],
		...
    ],
    "07/08/2010 00:00:00": [
		...
    ],
...
}