42matters is now part of the Similarweb family. Learn more here

Documentation

Google Play App Rank History API

Google Play App Rank History API. Retrieve comprehensive historical app rank insights for any Android app available on Google Play.

Definition

Endpoint:

GET https://data.42matters.com/api/v4.0/android/apps/ranks.json

Hits per request:

3

Rate limit:

3 QPS

Required plan:

Small or above.

Historical data:

default 30 days (up to 1 year with 'Historical Package')

Parameters

Name Required Description Available Values Default
access_token required Your access token for using this API. You can get it for FREE by signing up.
p required The package name identifying an Android application. Any publicly available Android app package name
country optional ISO code of the country. If no country is specified, US will be used. List of Supported Countries US
start_date optional The start date of the report A valid date in the format yyyy-MM-dd, for example: 2020-05-24
end_date optional The end date of the report. A valid date in the format yyyy-MM-dd, for example: 2020-05-30
days optional Set the date range from yesterday to the specified number of days in the past. Without Historical Package: Last 30 days. With Historical Package: up to 1 year 1
list_names optional Comma-separated list of list_name values. If no list_name is specified, all available list_names will be returned.
Name Description
topselling_free Top Selling Free
topselling_paid Top Selling Paid
movers_shakers Top Trending
topgrossing Top Grossing Apps
topselling_new_free Top New Free
topselling_new_paid Top New Paid
cat_keys optional Comma-separated list of cat_key values. If no cat_key is specified, all available cat_keys will be returned. ID of Google Play Categories
lang optional Return language-specific metadata. If no translation is available the default language of the app is used. Internationalized fields include t​itle, short_desc, description, what_is_new, screenshots. ID of Supported Languages en
app_country optional Return country-specific app metadata. Country-specific fields include currency, price, formattedPrice, userRatingCount, userRatingCountForCurrentVersion, averageUserRating, averageUserRatingForCurrentVersion. If the country is not supported, then the default metadata of the app is returned. ID of Supported Countries US
sort_order optional Ordering by date desc or asc asc
limit optional Number of ranks to return. 1-100 100
page optional Page based on the limit parameter, used for pagination. 1 - max pages. 1
callback optional If supplied, the response will use the JSONP format with a callback of the given name.

Responses

Status Code Indication Content-Type Body
200 Everything is OK application/json
Attribute Type Description
number_results Long Total number of results for this query
num_pages Long Maximum number of pages it's possible to iterate
has_next Boolean Flag indicating if there is a next page available
limit Long Number of results per request
page Long Current page number
package_name String The app package name (unique identifier)
title String App title
developer String App developer name
number_ratings Long Number of app ratings
rating Double App rating (from 0 to 5, 5 highest)
icon URL Full-sized icon. Format can be either webp or png. In order to request png format, remove the trailing "-rw" from the url.
icon_72 URL App icon (72x72 pixels)
price String App price with currency (if paid)
market_url URL A deep link to the app page on Google Play
start_date Date A date in the format: yyyy-MM-dd
end_date Date A date in the format: yyyy-MM-dd
country String Country code
country_name String Name of the country
max_position Long The maximum position in the response.
number_dates Long Number of dates in the response
dates Array of dates Sorted list of dates in the response
ranks Array of Objects Sorted list of rank objects in the response. Each rank contains: cat_key, category_name, list_name, list_title, date, position
404 The package name is not found application/json Error object
402 Your request exceeds what's allowed by your current subscription plan application/json Error object
403 Your access token is not valid application/json Error object
429 Your request rate is over the limit application/json Error object

Example Request

This request can also be imported into Postman. Check out our Postman integration guide.

Example Response

{
  "number_results": 69,
  "num_pages": 7,
  "has_next": true,
  "limit": 10,
  "page": 1,
  "package_name": "com.zhiliaoapp.musically",
  "start_date": "2025-05-17",
  "end_date": "2025-05-26",
  "country": "US",
  "country_name": "United States",
  "max_position": 10,
  "number_dates": 2,
  "dates": [
    "2025-05-17",
    "2025-05-18"
  ],
  "ranks": [
    {
      "cat_key": "SOCIAL",
      "category_name": "Social",
      "list_name": "movers_shakers",
      "list_title": "Top Trending",
      "date": "2025-05-17",
      "position": 10
    },
    {
      "cat_key": "SOCIAL",
      "category_name": "Social",
      "list_name": "topgrossing",
      "list_title": "Top Grossing Apps",
      "date": "2025-05-17",
      "position": 1
    },
    {
      "cat_key": "APPLICATION",
      "category_name": "All apps",
      "list_name": "topgrossing",
      "list_title": "Top Grossing Apps",
      "date": "2025-05-17",
      "position": 2
    },
    {
      "cat_key": "OVERALL",
      "category_name": "Overall",
      "list_name": "topgrossing",
      "list_title": "Top Grossing Apps",
      "date": "2025-05-17",
      "position": 2
    },
    {
      "cat_key": "APPLICATION",
      "category_name": "All apps",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2025-05-17",
      "position": 3
    },
    {
      "cat_key": "SOCIAL",
      "category_name": "Social",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2025-05-17",
      "position": 1
    },
    {
      "cat_key": "OVERALL",
      "category_name": "Overall",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2025-05-17",
      "position": 3
    },
    {
      "cat_key": "OVERALL",
      "category_name": "Overall",
      "list_name": "topgrossing",
      "list_title": "Top Grossing Apps",
      "date": "2025-05-18",
      "position": 2
    },
    {
      "cat_key": "SOCIAL",
      "category_name": "Social",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2025-05-18",
      "position": 1
    },
    {
      "cat_key": "SOCIAL",
      "category_name": "Social",
      "list_name": "topgrossing",
      "list_title": "Top Grossing Apps",
      "date": "2025-05-18",
      "position": 1
    }
  ],
  "title": "TikTok",
  "developer": "TikTok Pte. Ltd.",
  "number_ratings": 66219743,
  "rating": 4.2232794761657715,
  "icon": "https://play-lh.googleusercontent.com/BmUViDVOKNJe0GYJe22hsr7juFndRVbvr1fGmHGXqHfJjNAXjd26bfuGRQpVrpJ6YbA=s180",
  "icon_72": "https://play-lh.googleusercontent.com/BmUViDVOKNJe0GYJe22hsr7juFndRVbvr1fGmHGXqHfJjNAXjd26bfuGRQpVrpJ6YbA=s180-rw",
  "market_url": "https://play.google.com/store/apps/details?id=com.zhiliaoapp.musically&referrer=utm_source%3D42matters.com%26utm_medium%3Dapi",
  "price": ""
}

Last Modified: 7 Oct 2021


Automate Your Workflow With 42matters’ APIs


Integrate app data and intelligence into your existing workflows, dashboards, CRM platforms, messaging platforms, and more! Below is a selection of the third-party services that are compatible with 42matters’ APIs:



Salesforce

Salesforce

HubSpot

HubSpot

Slack

Slack

Intercom

Intercom

Pipedrive

Pipedrive

Zendesk

Zendesk

Gekoboard

Gekoboard

Klipfolio

Klipfolio

Dynamics

Dynamics


And many more!


CONTACT SALES