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:

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 .

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

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

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 title, short_desc, description, what_is_new, screenshots.

ID of Supported Languages

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

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.

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

Ranks for the TikTok app on Google Play:

https://data.42matters.com/api/v4.0/android/apps/ranks.json?p=com.zhiliaoapp.musically&days=10&limit=10&access_token=YOUR_ACCESS_TOKEN

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

Example Response

{
  "number_results": 54,
  "num_pages": 6,
  "has_next": true,
  "limit": 10,
  "page": 1,
  "package_name": "com.zhiliaoapp.musically",
  "start_date": "2023-09-12",
  "end_date": "2023-09-21",
  "country": "US",
  "country_name": "United States",
  "max_position": 4,
  "number_dates": 2,
  "dates": [
    "2023-09-12",
    "2023-09-13"
  ],
  "ranks": [
    {
      "cat_key": "SOCIAL",
      "category_name": "Social",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2023-09-12",
      "position": 1
    },
    {
      "cat_key": "OVERALL",
      "category_name": "Overall",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2023-09-12",
      "position": 3
    },
    {
      "cat_key": "APPLICATION",
      "category_name": "All apps",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2023-09-12",
      "position": 3
    },
    {
      "cat_key": "SOCIAL",
      "category_name": "Social",
      "list_name": "topgrossing",
      "list_title": "Top Grossing Apps",
      "date": "2023-09-12",
      "position": 1
    },
    {
      "cat_key": "APPLICATION",
      "category_name": "All apps",
      "list_name": "topgrossing",
      "list_title": "Top Grossing Apps",
      "date": "2023-09-12",
      "position": 2
    },
    {
      "cat_key": "OVERALL",
      "category_name": "Overall",
      "list_name": "topgrossing",
      "list_title": "Top Grossing Apps",
      "date": "2023-09-12",
      "position": 3
    },
    {
      "cat_key": "APPLICATION",
      "category_name": "All apps",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2023-09-13",
      "position": 3
    },
    {
      "cat_key": "SOCIAL",
      "category_name": "Social",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2023-09-13",
      "position": 1
    },
    {
      "cat_key": "SOCIAL",
      "category_name": "Social",
      "list_name": "topgrossing",
      "list_title": "Top Grossing Apps",
      "date": "2023-09-13",
      "position": 1
    },
    {
      "cat_key": "OVERALL",
      "category_name": "Overall",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "date": "2023-09-13",
      "position": 4
    }
  ],
  "title": "TikTok",
  "developer": "TikTok Pte. Ltd.",
  "number_ratings": 59501606,
  "rating": 4.390315055847168,
  "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: