App Store App Rank History API

App Store iOS App Rank History API. Retrieve comprehensive historical app rank insights for any iOS app available on the Apple App Store.

Definition

Endpoint:

GET https://data.42matters.com/api/v3.0/ios/apps/ranks.json

Hits per request:

3

Rate limit:

3 QPS

Required plan:

Small or above.

Historical data:

default 30 days (365 with 'Historical Plan')

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 .
id required The app ID on the iTunes store - (e.g for Facebook the ID is 284882215). Existing App ID on iTunes Store
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: Last 365 days 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
device_types optional Comma-separated list of Device Types. If no device_type is specified, all available device_types will be returned.
Value Information
iphone iPhone devices
ipad iPad devices
primaryGenreIds optional Comma-separated list of App Primary Genre Ids. If no primaryGenreId is specified, all available primaryGenreIds will be returned. ID of App Store Genres
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 are 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
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
trackId String Numeric unique identifier for the app assigned by Apple
trackCensoredName String App title
sellerName String Seller company name
userRatingCount Integer Number of ratings of the app for all versions
averageUserRating Double The average rating of the app for all versions (from 0 to 5, 5 highest)
artworkUrl512 URL Icon image with 512px square sizes
artworkUrl100 URL Icon image with 100px square sizes
formattedPrice String Price and currency of the app
trackViewUrl URL Link to the app on the Apple App Store
start_date Date A date in the format: yyyy-MM-dd
end_date Date A date in the format: yyyy-MM-dd
max_position Integer The maximum position among all ranks. Useful to set custom ranges in your charts.
number_dates Integer 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: country, country_name, primary_genre_id, primary_genre_name, list_name, list_title, positions (in the returned dates). If a position is null, it means the app is not in this chart on that day.
404 The track id/bundle id 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

{
  "trackId": "835599320",
  "start_date": "2021-06-05",
  "end_date": "2021-06-14",
  "max_position": 341,
  "number_dates": 10,
  "dates": [
    "2021-06-05",
    "2021-06-06",
    "2021-06-07",
    "2021-06-08",
    "2021-06-09",
    "2021-06-10",
    "2021-06-11",
    "2021-06-12",
    "2021-06-13",
    "2021-06-14"
  ],
  "ranks": [
    {
      "country": "US",
      "country_name": "United States",
      "primary_genre_id": 36,
      "primary_genre_name": "Overall",
      "list_name": "topgrossing",
      "list_title": null,
      "device_type": "ipad",
      "positions": [
        {
          "date": "2021-06-05",
          "position": 233
        },
        {
          "date": "2021-06-06",
          "position": 155
        },
        {
          "date": "2021-06-07",
          "position": 209
        },
        {
          "date": "2021-06-08",
          "position": 226
        },
        {
          "date": "2021-06-09",
          "position": 163
        },
        {
          "date": "2021-06-10",
          "position": 221
        },
        {
          "date": "2021-06-11",
          "position": 229
        },
        {
          "date": "2021-06-12",
          "position": 288
        },
        {
          "date": "2021-06-13",
          "position": 265
        },
        {
          "date": "2021-06-14",
          "position": 341
        }
      ]
    },
    {
      "country": "US",
      "country_name": "United States",
      "primary_genre_id": 6016,
      "primary_genre_name": "Entertainment",
      "list_name": "topgrossing",
      "list_title": null,
      "device_type": "ipad",
      "positions": [
        {
          "date": "2021-06-05",
          "position": 15
        },
        {
          "date": "2021-06-06",
          "position": 12
        },
        {
          "date": "2021-06-07",
          "position": 16
        },
        {
          "date": "2021-06-08",
          "position": 17
        },
        {
          "date": "2021-06-09",
          "position": 13
        },
        {
          "date": "2021-06-10",
          "position": 17
        },
        {
          "date": "2021-06-11",
          "position": 16
        },
        {
          "date": "2021-06-12",
          "position": 18
        },
        {
          "date": "2021-06-13",
          "position": 17
        },
        {
          "date": "2021-06-14",
          "position": 16
        }
      ]
    },
    {
      "country": "US",
      "country_name": "United States",
      "primary_genre_id": 36,
      "primary_genre_name": "Overall",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "device_type": "ipad",
      "positions": [
        {
          "date": "2021-06-05",
          "position": 12
        },
        {
          "date": "2021-06-06",
          "position": 11
        },
        {
          "date": "2021-06-07",
          "position": 11
        },
        {
          "date": "2021-06-08",
          "position": 10
        },
        {
          "date": "2021-06-09",
          "position": 9
        },
        {
          "date": "2021-06-10",
          "position": 11
        },
        {
          "date": "2021-06-11",
          "position": 13
        },
        {
          "date": "2021-06-12",
          "position": 12
        },
        {
          "date": "2021-06-13",
          "position": 11
        },
        {
          "date": "2021-06-14",
          "position": 11
        }
      ]
    },
    {
      "country": "US",
      "country_name": "United States",
      "primary_genre_id": 6016,
      "primary_genre_name": "Entertainment",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "device_type": "ipad",
      "positions": [
        {
          "date": "2021-06-05",
          "position": 3
        },
        {
          "date": "2021-06-06",
          "position": 4
        },
        {
          "date": "2021-06-07",
          "position": 4
        },
        {
          "date": "2021-06-08",
          "position": 4
        },
        {
          "date": "2021-06-09",
          "position": 4
        },
        {
          "date": "2021-06-10",
          "position": 4
        },
        {
          "date": "2021-06-11",
          "position": 4
        },
        {
          "date": "2021-06-12",
          "position": 4
        },
        {
          "date": "2021-06-13",
          "position": 4
        },
        {
          "date": "2021-06-14",
          "position": 4
        }
      ]
    },
    {
      "country": "US",
      "country_name": "United States",
      "primary_genre_id": 36,
      "primary_genre_name": "Overall",
      "list_name": "topgrossing",
      "list_title": null,
      "device_type": "iphone",
      "positions": [
        {
          "date": "2021-06-05",
          "position": 25
        },
        {
          "date": "2021-06-06",
          "position": 22
        },
        {
          "date": "2021-06-07",
          "position": 26
        },
        {
          "date": "2021-06-08",
          "position": 27
        },
        {
          "date": "2021-06-09",
          "position": 23
        },
        {
          "date": "2021-06-10",
          "position": 24
        },
        {
          "date": "2021-06-11",
          "position": 25
        },
        {
          "date": "2021-06-12",
          "position": 26
        },
        {
          "date": "2021-06-13",
          "position": 29
        },
        {
          "date": "2021-06-14",
          "position": 28
        }
      ]
    },
    {
      "country": "US",
      "country_name": "United States",
      "primary_genre_id": 6016,
      "primary_genre_name": "Entertainment",
      "list_name": "topgrossing",
      "list_title": null,
      "device_type": "iphone",
      "positions": [
        {
          "date": "2021-06-05",
          "position": 5
        },
        {
          "date": "2021-06-06",
          "position": 4
        },
        {
          "date": "2021-06-07",
          "position": 6
        },
        {
          "date": "2021-06-08",
          "position": 6
        },
        {
          "date": "2021-06-09",
          "position": 5
        },
        {
          "date": "2021-06-10",
          "position": 5
        },
        {
          "date": "2021-06-11",
          "position": 5
        },
        {
          "date": "2021-06-12",
          "position": 5
        },
        {
          "date": "2021-06-13",
          "position": 5
        },
        {
          "date": "2021-06-14",
          "position": 5
        }
      ]
    },
    {
      "country": "US",
      "country_name": "United States",
      "primary_genre_id": 36,
      "primary_genre_name": "Overall",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "device_type": "iphone",
      "positions": [
        {
          "date": "2021-06-05",
          "position": 4
        },
        {
          "date": "2021-06-06",
          "position": 4
        },
        {
          "date": "2021-06-07",
          "position": 4
        },
        {
          "date": "2021-06-08",
          "position": 4
        },
        {
          "date": "2021-06-09",
          "position": 4
        },
        {
          "date": "2021-06-10",
          "position": 3
        },
        {
          "date": "2021-06-11",
          "position": 3
        },
        {
          "date": "2021-06-12",
          "position": 3
        },
        {
          "date": "2021-06-13",
          "position": 3
        },
        {
          "date": "2021-06-14",
          "position": 3
        }
      ]
    },
    {
      "country": "US",
      "country_name": "United States",
      "primary_genre_id": 6016,
      "primary_genre_name": "Entertainment",
      "list_name": "topselling_free",
      "list_title": "Top Selling Free",
      "device_type": "iphone",
      "positions": [
        {
          "date": "2021-06-05",
          "position": 1
        },
        {
          "date": "2021-06-06",
          "position": 2
        },
        {
          "date": "2021-06-07",
          "position": 3
        },
        {
          "date": "2021-06-08",
          "position": 3
        },
        {
          "date": "2021-06-09",
          "position": 2
        },
        {
          "date": "2021-06-10",
          "position": 1
        },
        {
          "date": "2021-06-11",
          "position": 1
        },
        {
          "date": "2021-06-12",
          "position": 1
        },
        {
          "date": "2021-06-13",
          "position": 1
        },
        {
          "date": "2021-06-14",
          "position": 1
        }
      ]
    }
  ],
  "trackCensoredName": "TikTok",
  "sellerName": "TikTok Pte. Ltd.",
  "userRatingCount": 9499230,
  "averageUserRating": 4.7328,
  "artworkUrl512": "https://is3-ssl.mzstatic.com/image/thumb/Purple115/v4/d4/a5/72/d4a57274-f1bd-4700-5192-5cc570c2abd1/source/512x512bb.jpg",
  "artworkUrl100": "https://is3-ssl.mzstatic.com/image/thumb/Purple115/v4/d4/a5/72/d4a57274-f1bd-4700-5192-5cc570c2abd1/source/100x100bb.jpg",
  "trackViewUrl": "https://apps.apple.com/us/app/tiktok/id835599320?uo=4&at=10l9yE",
  "formattedPrice": "Free"
}

Last Modified: 29 Apr 2020


Automate your workflow


Bring app data into your existing workflow, dashboards, CRM, messaging platforms and many more services! Here a selection of third-party services we support:



Email

Email

Salesforce

Salesforce

HubSpot

HubSpot

Slack

Slack

Intercom

Intercom

Pipedrive

Pipedrive

Zendesk

Zendesk

Gekoboard

Gekoboard

Klipfolio

Klipfolio

Dynamics

Dynamics


And many more!


GET FREE INTEGRATIONS via Zapier!

Want to know more?

Schedule an appointment to see how our products can help grow your mobile business.


SCHEDULE A DEMO


Company

Products

Support

Free Tools

Legal



Linkedin Facebook Twitter

Copyright © 2021 42matters AG - All rights reserved

Applications listed on 42matters.com are from the Google Play™ Store, the Apple App Store®, the Amazon AppStore®, the Tencent Myapp®, the Apple TV App Store®, the Amazon Fire TV®, and the Roku Channel Store® and all the rights belong to their respective owners. Android™ and Google Play™ are trademarks of Google Inc. App Store®, iTunes® and TV App Store® are trademarks of Apple Inc. Amazon®, Amazon AppStore® and Amazon Fire TV® are trademarks of Amazon Inc. Tencent® and Tencent Myapp® are trademarks of Tencent Holdings Limited. Roku® and Roku Channel Store® are trademarks of Roku Inc. Any third party trademark and/or logo displayed on this website, shall NOT be interpreted as any sponsorship, endorsement and/or affiliation with 42matters.