Category Rankings

GET 2 Credits / Request / 30 days /ios/applications/{APPLICATION_ID}/rankings.json

Category Rankings allows you to fetch the evolution of the position of an app in it's category top charts rankings.

Category Rankings Request

Apple compiles 3 top charts for each category: one for the top free apps, one for the top paid apps, and the top grossing apps. The request allows to fetch the evolution of the ranking of an app in its charts for one of the types.

Header parameters
X-AppTweak-Key:
Your AppTweak API Key.
Path parameters
APPLICATION_ID:
Application ID for which you want to get the metadata.
Query parameters
country: string us

The two letter country code (ISO Alpha-2) you want to fetch the app in.

us. Get the list of our country codes, here.

device: string iphone

The device you want to fetch the application for.

iphone or ipad

start_date: string 90 Days ago

The first date for which to get data in YYYY-MM-DD format

The response will contain one entry per day between start_date and end_date

end_date: string Yesterday

The last date for which to get data in YYYY-MM-DD format

The response will contain one entry per day between start_date and end_date

type: string free

The type of chart to fetch

Possible values are: free, paid and grossing

GET /ios/applications/{APPLICATION_ID}/rankings.json

Request example
GET /ios/applications/545519333/rankings.json?country=de&device=iphone&start_date=2018-11-01&end_date=2018-11-03&type=free
cURL example
curl -X GET -H "X-Apptweak-Key: ${API_KEY}" https://api.apptweak.com/ios/applications/545519333/rankings.json?country=de&device=iphone&start_date=2018-11-01&end_date=2018-11-03&type=free

Category Rankings Response

The response to the category rankings request is a hash that contains: the start and end date of the selected time period, one list of rank for each top chart the app ranked on, and for each of those chart the maximum depth we were able to obtain.

A null rank in a top chart on a specific date means that we were not able to find your app in the specific top chart. A corresponding null in the max fetched entries means we did not fetch the chart at all.

Object properties
start_date: string

The detected start date of the period.

end_date: string

The detected end date of the period.

ranks: hash

A key value list of ranks. The key is the category ID (which can be found here) and the value is an array of rank. There will be one entry per day between start_date and end_date

max_fetched: hash

A key value list of the maximum depth AppTweak was able to fetch for each top chart. The key is the category ID (which can be found here) and the value is an array of the maximum rank AppTweak found. There will be one entry per day between start_date and end_date

Response Example

{
  "content": {
    "country": "de",
    "start_date": "2018-11-01",
    "end_date": "2018-11-03",
    "device": "iphone",
    "type": "free",
    "ranks": {
      "0": [
        33,
        26,
        25
      ],
      "6016": [
        2,
        2,
        2
      ]
    },
    "max_fetched": {
      "0": [
        1496,
        1497,
        1495
      ],
      "6016": [
        1499,
        1498,
        1497
      ]
    }
  },
  "metadata": {
    "request": {
      "path": "/applications/545519333/rankings.json",
      "store": "ios",
      "params": {
        "country": "de",
        "device": "iphone",
        "start_date": "2018-11-01T00:00:00+00:00",
        "end_date": "2018-11-03T00:00:00+00:00",
        "type": "free",
        "id": "545519333",
        "format": "json"
      },
      "performed_at": "2018-11-12 13:59:44 UTC"
    },
    "content": {
    }
  }
}