Application Rankings History

GET 1 Credit / Request + 1 Credit / Request / 30 days /android/applications/{APPLICATION_ID}/rankings.json

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

Application Rankings Request

Each rankings object contains the ordered ranks for the app in a chart on the selected period. A chart is defined per category, in a type (free, paid or grossing) for the selected country. 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.

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 /android/applications/{APPLICATION_ID}/rankings.json

Request example
GET /android/applications/com.king.candycrushjellysaga/rankings.json?country=us&start_date=2018-11-01&end_date=2018-11-15&type=free
cURL example
curl -X GET -H "X-Apptweak-Key: ${API_KEY}" https://api.apptweak.com/android/applications/com.king.candycrushjellysaga/rankings.json?country=us&start_date=2018-11-01&end_date=2018-11-15&type=free

Application Rankings History Response

The response to the application rankings history 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
country: string

The two letter country code (ISO Alpha-2).

start_date: string

The detected start date of the period.

end_date: string

The detected end date of the period.

type: string

The type of chart to fetch.

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": "us",
    "start_date": "2018-11-01",
    "end_date": "2018-11-15",
    "type": "free",
    "ranks": {
      "GAME_PUZZLE": [
        63,
        61,
        63,
        49,
        58,
        57,
        61,
        61,
        59,
        61,
        63,
        67,
        73,
        71,
        63
      ]
    },
    "max_fetched": {
      "GAME_PUZZLE": [
        500,
        500,
        500,
        500,
        500,
        500,
        500,
        500,
        500,
        500,
        500,
        500,
        500,
        500,
        500
      ]
    }
  },
  "metadata": {
    "request": {
      "path": "/applications/com.king.candycrushjellysaga/rankings.json",
      "store": "android",
      "params": {
        "country": "us",
        "start_date": "2018-11-01T00:00:00+00:00",
        "end_date": "2018-11-15T00:00:00+00:00",
        "type": "free",
        "id": "com.king.candycrushjellysaga",
        "format": "json"
      },
      "performed_at": "2018-11-27 01:08:01 UTC"
    },
    "content": {
    }
  }
}