Keywords Rankings

GET 3 Credits / Keyword / Application / 30 days /android/keywords/app-rankings.json

Keywords Rankings allow you to get the 90 days rankings for one or several applications for a keywords list. We compute the position of the apps for each keyword on a best effort basis and the list may thus be incomplete or even empty. However, once an App Keyword Ranking is performed asking for data for a specific keyword, the keyword is flagged in our system and fetched once a day. Subsequent calls for the same keyword should thus yield complete results.

Note that the default selected period is for 90 days, but you can provide your date range in order to extend the targetted period.

Keywords Rankings Request

This method returns the rankings for the provided keywords.

Header parameters
X-AppTweak-Key:
Your AppTweak API Key.
Query parameters
applications: string com.facebook.orca,com.whatsapp Required

A url encoded comma separated list of application IDs you wish to fetch rankings on. We allow a maximum of 5 applications per query.

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.

keywords: string toon,pop,blast,cubes Required

A url encoded comma separated list of keywords you wish to fetch stats on. We allow a maximum of 10 keywords per query.

language: string en

The two letter language (ISO Alpha-2) you want to fetch the application in.

en. Get the list of our language codes, here.

start_date: date

Start date, format: YYYY-MM-DD

end_date: date

End date, format: YYYY-MM-DD

GET /android/keywords/app-rankings.json

Request example
GET /android/keywords/app-rankings.json?country=us&language=us&keywords=photo,friend,share,free%20app&applications=com.facebook.orca,com.whatsapp&start_date=2018-12-01&end_date=2018-12-10
cURL example
curl -X GET -H "X-Apptweak-Key: ${API_KEY}" https://api.apptweak.com/android/keywords/app-rankings.json?country=us&language=us&keywords=photo,friend,share,free%20app&applications=com.facebook.orca,com.whatsapp&start_date=2018-12-01&end_date=2018-12-10

Keywords Rankings Response

The response is a JSON object. Each key of the object is one of the provided keywords, the matching value is a ranking object holding the ranks and the dates per application.

Object properties
end_date: datetime

The date of the last integer of the ranks array.

ranks: hash

Key/value pair containing an ordered list of integer giving the position of each targetted app in the search result of the keyword between start_date and end_date. Lower is better. null indicates that the app was not found in the chart on the matching day.

start_date: datetime

The date of the first integer of the ranks array.

total_size: array

An ordered list of integer giving the total number of applications for which the rankings have been calculated between start_date and end_date (Most of the time on 250 applications).

downloads: hash

The keys are the application ids and the values are an array of floats giving the estimated daily downloads for this app between start_date and end_date.

Response Example

{
  "content": {
    "photo": {
      "ranks": {
        "com.facebook.orca": [
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null
        ],
        "com.whatsapp": [
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null
        ]
      },
      "total_size": [
        250,
        250,
        250,
        250,
        250,
        250,
        250,
        250,
        250,
        250
      ],
      "start_date": "2018-12-01 00:00:00 +0000",
      "end_date": "2018-12-10 00:00:00 +0000",
      "downloads": {
        "com.facebook.orca": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "com.whatsapp": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ]
      }
    },
    "friend": {
      "ranks": {
        "com.facebook.orca": [
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null
        ],
        "com.whatsapp": [
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null
        ]
      },
      "total_size": [
        250,
        250,
        250,
        250,
        250,
        250,
        250,
        250,
        250,
        250
      ],
      "start_date": "2018-12-01 00:00:00 +0000",
      "end_date": "2018-12-10 00:00:00 +0000",
      "downloads": {
        "com.facebook.orca": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "com.whatsapp": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ]
      }
    },
    "share": {
      "ranks": {
        "com.facebook.orca": [
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null
        ],
        "com.whatsapp": [
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null,
          null
        ]
      },
      "total_size": [
        248,
        249,
        249,
        249,
        250,
        249,
        249,
        249,
        249,
        249
      ],
      "start_date": "2018-12-01 00:00:00 +0000",
      "end_date": "2018-12-10 00:00:00 +0000",
      "downloads": {
        "com.facebook.orca": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "com.whatsapp": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ]
      }
    },
    "free app": {
      "ranks": {
        "com.facebook.orca": [
          1,
          1,
          2,
          2,
          4,
          3,
          3,
          6,
          6,
          4
        ],
        "com.whatsapp": [
          7,
          10,
          9,
          7,
          10,
          5,
          5,
          11,
          5,
          15
        ]
      },
      "total_size": [
        248,
        248,
        247,
        247,
        248,
        248,
        248,
        248,
        248,
        248
      ],
      "start_date": "2018-12-01 00:00:00 +0000",
      "end_date": "2018-12-10 00:00:00 +0000",
      "downloads": {
        "com.facebook.orca": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "com.whatsapp": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ]
      }
    }
  },
  "metadata": {
    "request": {
      "path": "/android/keywords/app-rankings.json",
      "store": "android",
      "params": {
        "country": "us",
        "language": "us",
        "keywords": "photo,friend,share,free app",
        "applications": "com.facebook.orca,com.whatsapp",
        "start_date": "2018-12-01T00:00:00+00:00",
        "end_date": "2018-12-10T00:00:00+00:00",
        "format": "json"
      },
      "performed_at": "2019-07-15 10:46:22 UTC"
    },
    "content": {
    }
  }
}