Google Play Store API documentation

Applications

Applications allow you to fetch all the information that AppTweak has been able to gather about a specific app on the Google Play Store.

Please note that the example has been stripped of redundant data to keep the documentation as concise as possible. The API might return additional, undocumented fields in the JSON, which your app should not rely upon.

The Application Request

In AppTweak, you always fetch an App, in a specific country, in a specific language, on a specific device. We reply with all the information we have for this App. Time based data like reviews and rank history are limited to a 30-day window.

Parameters
country:
Optional. Default: us The two letter country code you want to fetch the app in.
language:
Optional. Default: en The two letter language you want to fetch the application in.

Retrieve partial information

For ease of use, we offer alternative methods to query our database. These methods only return a subset of the application object. They take the same parameters as the regular application request.

Alternatives methods
reviews
Only returns the reviews list of the application object.
ratings
Only returns the ratings hash of the application object.
information
Only returns the store_info hash of the application object.

The Application Object

The response to the application request is a deep JSON hash containing all necessary data to get an overview of the application state on the Google Play Store, and of its evolution in the rankings and reviews in the last 30-days.

application_id:
string The ID given by the developer to its application. Google forces these names to be valid Java package names.
rankings:
array A list of rankings objects. See rankings format.
developer:
hash Key/value pairs describing the developer.
store_info:
hash Key/value pairs describing how the application looks on the Google Play Store. See store_info format.
ratings:
hash Key/value pairs with fields that describe the ratings of the aplication of its current version and for all version combined. See ratings format.
reviews:
array A list of reviews objects. See reviews format. We limit the reviews returned by the API to those written in the last 30-days.
country_rankings:
array A list of country rankings objects. See country rankings format.
country_code:
string The two letter code of the country we are returning the information from.
language:
string The two letter code of the language we are returning the information in.
The ratings hash

The ratings hash holds the state of the app ratings on the Google Play Store. It holds two ratings object : one for the current version of the App, and one for all versions combined. The two objects are held respectively under the current_version and all_version keys.

Below are the key/values for each ratings object.

average:
float (between 0.0 and 5.0) The average rating of the App.
count:
integer The number of ratings this app has received.
star_count:
hash Drilldown of the votes by star count. Each key is a star number (between 1 and 5) and the value is the number of votes that were cast with this number of star.
The rankings hash

Each rankings object contains the ordered ranks for the last 30-days for the app in a chart. A chart is defined per category, in a type (free, paid or grossing) for the selected country.

category_id:
string The ID of the category this rankings object is referring to. The special category_id ALL is used to refer to the global rankings across all categories combined.
type:
string ( free | paid | grossing ) The kind of chart this rankings object is referring to.
first_date:
time The date of the first integer of the ranks array.
last_date:
time The date of the last integer of the ranks array.
ranks:
array Ordered list of integer giving the rank of the app in the chart between first_date and last_date. Lower is better. null indicates that the app was not found in the chart on the matching day. The array is always 30 elements long, last_date is thus always 29 days later than first_date.
The store_info hash

The store_info hash contains the information that is used to generate the app preview on the Google Play Store.

versions:
array A list of version hash. Each version hash specifies the version number, the date on when it was released and the release notes in the chosen language.
icon:
string The URL of the icon as it appears on the Google Play Store.
genres:
array The list of category the app is listed on. The special category_id ALL is used to refer to the global rankings across all categoies combined.
title:
string The app name as it appears on the Google Play Store, in the chosen language.
slug:
string URL friendly version of the app name.
description:
string The app description as it appears on the Google Play Store, in the chosen language.
permissions:
array The list of permissions the app may try to access. Notably, the presence of the permission android.permission.BILLING indicates the presence of in-app purchases.
price:
string The price of the app as displayed on the Google Play Store.
screenshots:
array List of application screenshot urls.
videos:
array List of application videos urls.
The review List

The review list contains a series of review entries describing comments made by users on the app in the selected country. We limit the reviews returned by the API to those written in the last 30-days.

date:
time The time at which the review was submitted by the user.
author:
hash A hash describing the comment's author. We provide the author name, a url to its photo and the url of his Google Plus profile.
title:
string The review title.
content:
string The "body" of the review, its main content.
version:
string The version of the app the review was submitted for.
rating:
integer ( 1 => 5 ) The number of stars the user gave to the App.
The country_rankings list

The country_ranking list contains country_rankings entries describing the current worldwide state of the app for a specific type of chart.

category_id:
string The ID of the category this rankings object is referring to.
type:
string ( free | paid | grossing ) The kind of chart this rankings object is referring to.
ranks:
hash Key/value pairs describing the current state of the app in the chart. Each key is a two letter country code, and the value is an integer holding the rank (lower is better) of the app in that country.
Definition
GET /android/applications/{APPLICATION_ID}.json



Partial Information
GET /android/applications/{APPLICATION_ID}/reviews.json
GET /android/applications/{APPLICATION_ID}/ratings.json
GET /android/applications/{APPLICATION_ID}/information.json



Example Requests
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/applications/com.facebook.katana.json?country=be&language=nl

$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/applications/com.shazam.android/reviews.json?country=es&language=es

$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/applications/com.rovio.angrybirds/ratings.json?country=de&language=en

$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/applications/com.boxer.email/information.json?country=fr&language=fr



Example Object
{
  "application_id": "com.facebook.orca",
  "country_code": "us",
  "country_rankings": [
      {
          "category_id": "ALL",
          "ranks": {"ae": 3, "at": 3, "au": 1, "be": 2, "br": 3, "ca": 1, "de": 3, "es": 5, "fr": 2, "gb": 3, "hu": 2, "id": 3, "in": 3, "it": 3, "jp": 34, "my": 3, "nl": 4, "nz": 1, "ph": 2, "pl": 1, "pt": 2, "qa": 3, "ru": 135, "sa": 4, "sg": 7, "th": 2, "tr": 3, "tw": 16, "ua": 47, "us": 1, "vn": 3, "za": 3 },
          "type": "free"
      },
      ...
  ],
  "developer": {
      "email": "android-support@fb.com",
      "name": "Facebook",
      "website": "http://www.facebook.com/apps/application.php?id=256002347743983"
  },
  "language": "en",
  "rankings": [
      {
          "category_id": "COMMUNICATION",
          "country_code": "us",
          "end_date": "2015-09-29 00:00:00 +0000",
          "ranks": [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
          "start_date": "2015-08-31 00:00:00 +0000",
          "type": "free"
      },
      ...
  ],
  "ratings": {
      "average": 3.884218454360962,
      "count": 19848906,
      "star_count": {
          "1": 3052968,
          "2": 969862,
          "3": 1916447,
          "4": 3192692,
          "5": 10716937
      }
  },
  "reviews": [
      {
          "author": {
              "name": "Erlix Abulencia",
              "photo": "https://lh5.googleusercontent.com/-VUwhgvYWt1U/AAAAAAAAAAI/AAAAAAAAABE/l2bhXVf_OYE/photo.jpg",
              "profile": "https://plus.google.com/106683571474060374280"
          },
          "body": "Messenger and fb lite don't connect or do not detect each other. Please make the messenger respond to the fb lite, just like the original fb app",
          "date": "2015-09-16 12:14:58 UTC",
          "id": "gp:AOqpTOGEIbh9kyfI2Br7q8hPNAwS-D6V5jqKhrvrbDz1HH1BX3yldI1_rfKP2TJzKQ-mEnLGDvHpGu2Nh-orbzo",
          "rating": 3,
          "title": "Connection with fb lite",
          "version": "33.0.0.30.250"
      },
      ...
  ],
  "store_info": {
    "description": "Instantly reach the people in your lifeā€”for free. Messenger is just like texting, but you don't have to pay for every message (it works with your data plan).
Not just for Facebook friends: Message people in your phone book and just enter a phone number to add a new contact.
Group chats: Create groups for the people you message most. Name them, set group photos and keep them all in one place.
Photos and videos: Shoot videos and snap selfies or other photos right from the app and send them with one tap.
Chat heads: Keep the conversation going while you use other apps.
Free calls: Talk as long as you want, even with people in other countries. (Calls are free over Wi-Fi. Otherwise, standard data charges apply.)
Even more ways to message:
Bring your conversations to life with stickers.
Preview your gallery photos and videos without leaving the conversation--then choose the perfect ones to send.
Record voice messages when you have more to say.
Extra features:
Know when people have seen your messages.
Forward messages or photos to people who weren't in the conversation.
Search for people and groups to quickly get back to them.
Turn on location to let people know when you're nearby.
See who's available on Messenger and who's active on Facebook.
Create shortcuts to get to any conversation right from your home screen.
Turn off notifications when you're working, sleeping or just need a break.
Stay logged in so you never miss a message.", "genres": [ "COMMUNICATION" ], "icon": "https://lh5.ggpht.com/0VYAvZLR9YhosF-thqm8xl8EWsCfrEY_uk2og2f59K8IOx5TfPsXjFVwxaHVnUbuEjc", "permissions": [ "com.facebook.katana.provider.ACCESS", "android.permission.INTERNET", "android.permission.GET_ACCOUNTS", "android.permission.ACCESS_NETWORK_STATE", "android.permission.WAKE_LOCK", "android.permission.VIBRATE", "android.permission.READ_CONTACTS", "android.permission.READ_CALL_LOG", "android.permission.READ_PROFILE", "android.permission.WRITE_EXTERNAL_STORAGE", "android.permission.READ_PHONE_STATE", "android.permission.ACCESS_WIFI_STATE", "android.permission.RECEIVE_BOOT_COMPLETED", "android.permission.READ_SYNC_SETTINGS", "android.permission.RECEIVE_MMS", "android.permission.READ_SMS", "android.permission.WRITE_SMS", "android.permission.SEND_SMS", "android.permission.CHANGE_NETWORK_STATE", "android.permission.RECORD_AUDIO", "android.permission.SYSTEM_ALERT_WINDOW", "android.permission.CALL_PHONE", "android.permission.MODIFY_AUDIO_SETTINGS", "android.permission.DOWNLOAD_WITHOUT_NOTIFICATION", "android.permission.AUTHENTICATE_ACCOUNTS", "android.permission.BLUETOOTH", "android.permission.MANAGE_ACCOUNTS", "android.permission.PROCESS_OUTGOING_CALLS", "android.permission.WRITE_CONTACTS", "android.permission.WRITE_SYNC_SETTINGS", "com.facebook.orca.provider.ACCESS", "com.facebook.permission.prod.FB_APP_COMMUNICATION", "android.permission.CAMERA", "android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_COARSE_LOCATION", "com.google.android.providers.gsf.permission.READ_GSERVICES", "android.permission.READ_EXTERNAL_STORAGE", "com.facebook.orca.permission.CROSS_PROCESS_BROADCAST_MANAGER", "android.permission.BATTERY_STATS", "com.android.launcher.permission.INSTALL_SHORTCUT", "com.facebook.receiver.permission.ACCESS", "com.sec.android.provider.badge.permission.READ", "com.sec.android.provider.badge.permission.WRITE", "com.htc.launcher.permission.READ_SETTINGS", "com.htc.launcher.permission.UPDATE_SHORTCUT", "com.sonyericsson.home.permission.BROADCAST_BADGE", "com.facebook.home.permission.WRITE_BADGES", "com.google.android.c2dm.permission.RECEIVE", "com.facebook.orca.permission.C2D_MESSAGE", "com.nokia.pushnotifications.permission.RECEIVE", "com.facebook.orca.permission.RECEIVE_ADM_MESSAGE", "com.amazon.device.messaging.permission.RECEIVE", "android.permission.RECEIVE_SMS" ], "price": "", "screenshots": [ "https://lh5.ggpht.com/S3udjKLR0045VRTGmKSCRq6n_-JVM084xH36SYUmjRnc8zZ2Gcq8eL7bixe-cscP_A", "https://lh4.ggpht.com/Idi8NCyRZHGQ8V1h64dGqD-N7PGym27FghdYtRqCY1H5HP5wRZwjISS8RB2XXnwh6Q", "https://lh6.ggpht.com/reXX4Sm0tmG5vu534eddDzgBW8R3s3ysmVCpMuXphHSDXct92G8vRpJQis7ZgCHe0Q", "https://lh5.ggpht.com/2FjQK1nkRoihPnafEG3KxuO5UkRDjZKfHUPcZgtz1jgB-zpKg9tduPEuX2jjK23WpwKv", "https://lh5.ggpht.com/dH_Znb__NjJkyQ0_HW4TPniO3pnfXqhVF9xQ2r06bj_z0PGXIKIIxw0GlvDmKWYUDw", "https://lh6.ggpht.com/qvqDEwA-q0qKrXMfMTaI6GYymqI1sdmS00QYoEYNn_fR2Eh2hIsHKs-D_9c1q9EV5m7N" ], "slug": "messenger", "title": "Messenger", "versions": [ { "release_date": "31 Aug 2015", "release_notes": "", "version": "37.0.0.28.158" }, ... ], "videos": [] } }

Search & Tops

Search and tops requests allow you to retrieve lists of applications. For each application we return the fields needed to build a preview snippet in the language specified in the request.

Searches allow you to query the Google Play Store for a term and get the ordered list of applications that would appear on a user device when he types that specific term on the Google Play Store search box. The first application is the one that would appear on top of the user result page. Additionaly the total number of applications responding to the search term.

Parameters
term:
Mandatory The url encoded search term to look for.
country:
Optional. Default: us The two letter country code you want to fetch the application in.
language:
Optional. Default: en The two letter language you want to fetch the application in.
num:
Optional. Default: 10. Possible Values : Between 0 and 50 The number of results for which details should be provided

Get a Top Chart

Top chart allows you to fetch the most popular applications for a category and type in a country for a device. We return the top 200 applications. Results are updated daily. The first application is the one that has the best rank for the requested chart.

Parameters
country:
Optional. Default: us The two letter country code you want to fetch the application in.
language:
Optional. Default: en The two letter language you want to fetch the application in.
type:
Optional. Default: free. Possible Values : free | paid | grossing The kind of chart you want to fetch.

The Application Preview

The response to the Top & Search requests is an ordered list of application snippets. Each application snippet is a JSON hash containing all necessary data to generate a preview of the application like displayed on the Google Play Store search results and top charts.

id:
string The ID given by the developer to its application.
title:
string The application name as it appears on the Google Play Store, in the chosen language.
icon:
string The URL of the icon as it appears on the Google Play Store.
developer:
string The application developer name.
price:
string The price of the application as displayed on the Google Play Store.
genres:
array The list of category the app is listed on.
Definition
GET /android/searches.json

GET /android/categories/{CATEGORY_ID}/top.json



Example Request
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/searches.json?term=angry&country=be&language=nl

$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/categories/BUSINESS/top.json?country=fr&language=fr



Example Object
[
  {
    "developer": "Facebook",
    "genres": [
        "COMMUNICATION"
    ],
    "icon": "https://lh5.ggpht.com/0VYAvZLR9YhosF-thqm8xl8EWsCfrEY_uk2og2f59K8IOx5TfPsXjFVwxaHVnUbuEjc",
    "id": "com.facebook.orca",
    "price": "",
    "title": "Messenger"
  },
  ...
]


App Top Keywords

App top keywords allows you to retrieve a list of keywords an app is performing well on. This is useful to investigate the keywords you should target.

Get App Top Keywords 100 Credits / Request

This method resturns the list of keywords on which the app is ranked in the top 50 when a user performs a search in the selected country, language and device.

Parameters
country:
Optional. Default: us The two letter country code you want to fetch the keywords in.
language:
Optional. Default: en. Possible values : en | fr | nl | de | pt | es | it | ru The two letter language you want to fetch the keywords in.

The App Keywords Object

The response is a list of keyword/ranking hash, which links each top keyword with the ranking of the app for that keyword.

keyword:
string The keyword this keyword/ranking object is referring to.
ranking:
integer The ranking of the app for the keyword.
Definition
GET /android/applications/{APPLICATION_ID}/keywords/top.json



Example Request
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/applications/com.squareenixmontreal.lcgo/keywords/top.json



Example Object
[
  {
    "keyword": "tombs",
    "ranking": 2
  },
  {
    "keyword": "relic",
    "ranking": 3
  },
  {
    "keyword": "tomb raider",
    "ranking": 3
  },
  {
    "keyword": "imaginary",
    "ranking": 4
  },
  ...
]

Keywords Stats

Keywords Stats allow you to fetch information about the popularity and competition of a given keyword. This is useful to estimate if it would be intetresting to put an emphasis on a given word in the app title, description or to target it in the keywords field.

Get Keywords Stats 10 Credits / Keyword

This method returns the list of provided keywords and evaluates the volume and competiton in a given country, language and device.

Parameters
keywords:
Mandatory A url encoded comma separated list of keywords you wish to fetch stats on. We allow a maximum of 10 keywords per query.
country:
Optional. Default: us The two letter country code you want to fetch the keywords in.
language:
Optional. Default: en. Possible values : en | fr | nl | de | pt | es | it | ru The two letter language you want to fetch the keywords in.

The Keywords Stats Object

The response is a hash which links each keyword with its stats. The keys of the hash are the provided keywords and the values are stats objects.

competition:
float [0..100] A score between 0 and 100 indicating how competitive the keyword is. Competitive keywords match more apps. It is therefore harder to get a good ranking on such keywords. Lower competitive keywords are better to target.
volume:
float [0..100] A score between 0 and 100 indicating how popular the keyword is. Popular keywords are more likely to be searched on the App Store and tend to generate more downloads. It is therefore more interesting to be well ranked keywords with a high volume.
kei:
float [0..100] KEI stand for "Keyword Efficiency Index". It's a score between 0 and 100 taking into account both the volume and competition. It's a measure of the risk/reward associated to each keyword. A high KEI indicates that the keyword is a good candidate for App Store Optimization (high volume and low competition).
competition_details:
hash A hash holding additional information about the competiton. Currently only holds the sub key search_result_size wich provides the precise number of apps in the App Store search results when a search is performed on the keyword.
volume_details:
hash A hash holding additional information about the volume. Currently only available on single words (no spaces). Holds the Following sub keys : language_frequency which is a score between 0 and 100 indicating how often is the word used in the common language. web_volume is an estimation of the number of monthly queries made on that keyword on Google. word_brands contains a per continent list of known brands containing that keyword. appstore_hints containes a list of 1,2 or 3 letters combinations in the data/results subkey which, if typed in the appstore search field, lead to Apple suggesting the keyword as a popular search term. For each hint, we provide the position (lower = better), the complete hint, and the date at which it was found. The score subkey is a numerical computation indicates how often the keyword is hinted by Apple.
Definition
GET /android/keywords/stats.json



Example Request
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/keywords/stats.json?keywords=arcade%2Cimperial%2Ctomb%20raider&country=us&language=en



Example Object
{
  "arcade": {
    "competition": 96.13846996726187,
    "volume": 95.04833326410453,
    "kei": 51.19448656666268,
    "competition_details": {
      "total_size": 248
    },
    "volume_details": {
      "language_frequency": 33.89,
      "appstore_hints": {
        "data": {
          "results": {
            "ar": [
              {
                "position": 2,
                "updated_at": "2016-01-27 11:39:16 UTC",
                "hint": "arcade games"
              }
            ],
            "aec": [
              {
                "position": 3,
                "updated_at": "2016-01-27 11:46:29 UTC",
                "hint": "arcade"
              }
            ],
            "arc": [
              {
                "position": 1,
                "updated_at": "2016-01-27 11:49:31 UTC",
                "hint": "arcade games"
              },
              {
                "position": 3,
                "updated_at": "2016-01-27 11:49:31 UTC",
                "hint": "arcade games free"
              },
              {
                "position": 5,
                "updated_at": "2016-01-27 11:49:31 UTC",
                "hint": "arcade"
              }
            ],
            "arx": [
              {
                "position": 4,
                "updated_at": "2016-01-27 11:49:45 UTC",
                "hint": "arcade"
              }
            ]
          },
          "score": 266.5691289152112
        },
        "date": "2016-04-15 16:41:12 UTC"
      },
      "web_volume": 33100,
      "world_brands": {}
    }
  },
  "imperial": {
    "competition": 41.065648211890476,
    "volume": 73.27869695453856,
    "kei": 79.82567352619974,
    "competition_details": {
      "total_size": 250
    },
    "volume_details": {
      "language_frequency": {},
      "appstore_hints": {
        "data": {
          "results": {
            "pfs": [
              {
                "position": 3,
                "updated_at": "2016-01-27 13:35:02 UTC",
                "hint": "imperial pfs"
              }
            ]
          },
          "score": 1.5317230265487634
        },
        "date": "2016-04-15 16:48:44 UTC"
      },
      "web_volume": 33100,
      "world_brands": {
        "north-america": [
          "Canadian Imperial Bank",
          "Imperial Oil"
        ]
      }
    }
  },
  "tomb raider": {
    "competition": 29.84693667570924,
    "competition_details": {
      "total_size": 167
    },
    "volume_details": {},
    "volume": 23.507101331684957,
    "kei": 28.244502348764623
  }
}

Suggested Keywords

Suggested Keywords allow you to get a list of keyword that we think are relevant to the application. Those keywords are fetched from various sources including : the app title, description, reviews, the app top keywords, the category top keywords and ordered by relevance and volume. This is usefull when looking for new keywords to target or to confirm the relvance of your title and description.

Get App Suggested Keywords 200 Credits / Request

This method returns the top 200 most relevant keywords we found.

Parameters
country:
Optional. Default: us The two letter country code you want to fetch the keywords in.
language:
Optional. Default: en. Possible values : en | fr | nl | de | pt | es | it | ru The two letter language you want to fetch the keywords in.

The Suggesed Keywords List Object

The response is an array. Each element of the array corresponding to a suggested keyword.

keyword:
string The suggested keyword
relevance:
float A score indicating how relevant the keyword is to the app
Definition
GET /android/applications/{APPLICATION_ID}/keywords/suggested.json



Example Request
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/applications/com.shazam.android/keywords/suggested.json



Example Object
[
  {
    "keyword": "shazam",
    "relevance": 646.7272134386297
  },
  {
    "keyword": "music",
    "relevance": 357.56669501952405
  },
  {
    "keyword": "song",
    "relevance": 144.43781353546026
  },
  {
    "keyword": "tap",
    "relevance": 130.0378638140512
  },
  {
    "keyword": "identify",
    "relevance": 123.40469505861114
  },
  {
    "keyword": "play",
    "relevance": 119.45734531057589
  },
  {
    "keyword": "songs",
    "relevance": 113.27586343654782
  },
  {
    "keyword": "lyrics",
    "relevance": 93.24135878014204
  },
  ...
]

App Keywords Competitors

Suggested Keywords allow you to get a list of applications that are competing with the given application on search result. These application are ranked at similar positions on the app main keywords. This is usefull to watch for new competitors, or to check the app position in the market.

Get App Keywords Competitors 100 Credits / Request

This method returns the top 10 most relevant competitors we found.

Parameters
country:
Optional. Default: us The two letter country code you want to fetch the keywords in.
language:
Optional. Default: en. Possible values : en | fr | nl | de | pt | es | it | ru The two letter language you want to fetch the keywords in.

The Keywords Competitors List Object

The response is an array. Each element of the array corresponding to a competitor.

id:
integer The ID given by the developer to its application.
title:
string The App name as it appears on the Play Store, in the chosen language.
icon:
string The URL of the icon as it appears on the Play Store.
genres:
array The list of category the app is listed on. See the supported categories list to match the category_id to it's human friendly name.
price:
string The price of the app as displayed on the App Store.
rating:
float (between 0.0 and 5.0) The average rating of the App.
version:
string The current version of the App.
Definition
GET /android/applications/{APPLICATION_ID}/keywords/competitors.json



Example Request
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/applications/com.walmart.android/keywords/competitors.json



Example Object
[
  {
    "id": "com.thehomedepot",
    "title": "The Home Depot",
    "icon": "https://lh3.ggpht.com/kwMcMDLzPptJz4TKwwetP4On4h89czigUbwdG9L_U7KulyaDa1kaXq1Raj8DSdPAlxM",
    "genres": [
      "SHOPPING"
    ],
    "price": "",
    "rating": 4.313284873962402,
    "version": "4.17"
  },
  {
    "id": "com.bestbuy.android",
    "title": "Best Buy",
    "icon": "https://lh4.ggpht.com/VJy0TKiXvzmKtXu0IAGxv1JUp9ky7dLqypHEgGj_edartV3IGewh7TZ-mUucLbmF-A",
    "genres": [
      "SHOPPING"
    ],
    "price": "",
    "rating": 4.2423834800720215,
    "version": "9.11.0"
  },
  {
    "id": "com.target.ui",
    "title": "Target",
    "icon": "https://lh3.googleusercontent.com/dL5wUTeOrTETTKAw1XiJcO6i3TvFJn3zOSKMBcGkzt42Kxt8jFHPHbtbqCvzZiFVcw",
    "genres": [
      "SHOPPING"
    ],
    "price": "",
    "rating": 3.959721565246582,
    "version": "4.9.171.2"
  },
  ...
]

App Keywords Rankings

The keywords rankings allow you to get the 90 days rankings of a selected app for a keyword list. We compute the position of the app 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 specifi keyword, the keyword is flagged in our system and fetched once a day. Subsequent calls for the same keyword should thus yield complete results.

Get App Keywords Rankings 10 Credits / Keyword

This method returns the rankings for the provided keywords.

Parameters
keywords:
Mandatory A url encoded comma separated list of keywords you wish to fetch rankings for. We allow a maximum of 10 keywords per query.
country:
Optional. Default: us The two letter country code you want to fetch the keywords in.
language:
Optional. Default: en. Possible values : en | fr | nl | de | pt | es | it | ru The two letter language you want to fetch the keywords in.

The Keywords Rankings Object

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

start_date:
time The date of the first integer of the ranks array.
end_date:
time The date of the last integer of the ranks array.
ranks:
array Ordered list of integer giving the position of the 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. The array is always 90 elements long, end_date is thus always 89 days later than start_date.
Definition
GET /ios/applications/{APPLICATION_ID}/keywords/rankings.json



Example Request
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/applications/com.runtastic.android/keywords/rankings.json?keywords=sport,run,gps



Example Object
{
  "sport": {
    "ranks": [85, 79, 81, 88, 98, ..., 110, 132],
    "start_date": "2016-03-16 00:00:00 +0000",
    "end_date": "2016-06-13 00:00:00 +0000"
  },
  "run": {
    "ranks": [10, 10, 10, 10, 10, ..., 10, 10],
    "start_date": "2016-03-16 00:00:00 +0000",
    "end_date": "2016-06-13 00:00:00 +0000"
  },
  "gps": {
    "ranks": [54, 86, 86, 72, 73, ..., 64, 39],
    "start_date": "2016-03-16 00:00:00 +0000",
    "end_date": "2016-06-13 00:00:00 +0000"
  }
}

Category Top Keywords

The category top keywords gives the most popular keyword for a given category. This is computed by looking at the best keywords for the app present at the top of each cateogry.

Get Category Top Keywords 100 Credits / Request

This method returns top keywords for the provided category. We return the top 50 keywords.

Parameters
country:
Optional. Default: us The two letter country code you want to fetch the application in.
language:
Optional. Default: en The two letter language you want to fetch the application in.
type:
Optional. Default: free. Possible Values : free | paid The kind of chart you want to fetch.

The Keywords Rankings Object

The response is a list of objects. Each of these object is a keyword

keyword:
string The keyword
score:
integer A measure of how popular the keyword is in the category
stats:
object For each keyword we provide the volume, competiton and kei.
Definition
GET /android/categories/{CATEGORY_ID}/keywords/top.json



Example Request
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/categories/BUSINESS/keywords/top.json?country=ru&language=en



Example Object
[
  {
    "keyword": "job",
    "score": 26,
    "stats": {
      "competition": 3.654035646280031,
      "volume": 100,
      "kei": 146.34596435371998
    }
  },
  {
    "keyword": "office",
    "score": 21,
    "stats": {
      "competition": 88.69021715674896,
      "volume": 100,
      "kei": 61.309782843251035
    }
  },
  {
    "keyword": "scanner",
    "score": 15,
    "stats": {
      "competition": 89.66729835524222,
      "volume": 100,
      "kei": 60.332701644757776
    }
  },
  {
    "keyword": "automatic",
    "score": 15,
    "stats": {
      "competition": 57.9107838767662,
      "volume": 95.57873386117518,
      "kei": 88.01770679326805
    }
  },
  {
    "keyword": "page",
    "score": 17,
    "stats": {
      "competition": 82.0935288829961,
      "volume": 91.68127590303949,
      "kei": 62.25751914079818
    }
  },
  {
    "keyword": "cisco",
    "score": 17,
    "stats": {
      "competition": 41.0089221809276,
      "volume": 90.20163257964975,
      "kei": 98.31173155895982
    }
  },
  ...
]

Miscellaneous

List of country codes

Country Name Country Code Languages
Australia au en
Austria at en
Belgium be en, fr, nl
Brazil br en, pt
Canada ca en, fr
China cn en, cn
France fr en, fr
Germany de en, de
Hungary hu en
India in en, in
Indonesia id en
Italy it en, it
Japan jp en, jp
Malaysia my en
Netherlands nl en, nl
New Zealand nz en
Philippines ph en
Poland pl en
Portugal pt en, pt
Qatar qa en
Russia ru en, ru
Saudi Arabia sa en
Singapore sg en, cn
South Africa za en
Spain es en, es
Taiwan tw en, cn
Thailand th en
Turkey tr en
Ukraine ua en
United Arab Emirates ae en
United Kingdom gb en
United States us en, es
Vietnam vn en

List of categories

Category Name Category Code
All ALL
Android Wear ANDROID_WEAR
Books & Reference BOOKS_AND_REFERENCE
Business BUSINESS
Comics COMICS
Communication COMMUNICATION
Education EDUCATION
Entertainment ENTERTAINMENT
Finance FINANCE
Health & Fitness HEALTH_AND_FITNESS
Libraries & Demo LIBRARIES_AND_DEMO
Lifestyle LIFESTYLE
app Wallpaper APP_WALLPAPER
Media & Video MEDIA_AND_VIDEO
Medical MEDICAL
Music & Audio MUSIC_AND_AUDIO
News & Magazines NEWS_AND_MAGAZINES
Personalization PERSONALIZATION
Photography PHOTOGRAPHY
Productivity PRODUCTIVITY
Shopping SHOPPING
Social SOCIAL
Sports SPORTS
Tools TOOLS
Transportation TRANSPORTATION
Travel & Local TRAVEL_AND_LOCAL
Weather WEATHER
App Widgets APP_WIDGETS
Game GAME
Family FAMILY
Game Action GAME_ACTION
Game Adventure GAME_ADVENTURE
Game Arcade GAME_ARCADE
Game Board GAME_BOARD
Game Card GAME_CARD
Game Casino GAME_CASINO
Game Casual GAME_CASUAL
Game Educational GAME_EDUCATIONAL
Game Music GAME_MUSIC
Game Puzzle GAME_PUZZLE
Game Racing GAME_RACING
Game Role Playing GAME_ROLE_PLAYING
Game Simulation GAME_SIMULATION
Game Sports GAME_SPORTS
Game Strategy GAME_STRATEGY
Game Trivia GAME_TRIVIA
Game Word GAME_WORD
Family Action & Adventure FAMILY_ACTION
Family Brain Games FAMILY_BRAINGAMES
Family Creativity FAMILY_CREATE
Family Education FAMILY_EDUCATION
Family Music & Video FAMILY_MUSICVIDEO
Family Pretend Play FAMILY_PRETEND