Apptopia Data API

New estimates models release

On 2023-09-28 we have released new estimates models data which offers better data quality and precision. That's why all app-estimates related datapoins are going to support versioning: model_version optional request argument. By default (if not provided): it is settled as v2.0 (old model estimates), for new one please specify it as v3.0.

Please also take into considerations that we're suppressing support for the following app-estimates related datapoints:

• ad_revenue (amount of revenue coming from ads monetization)
  
• breakout (breakout likelihood %)

Overview

Apptopia data API exposes raw data on mobile app stores. Currently supported stores are Google Play, iTunes App Store, Tencent, Xiaomi and Mobile 360 Stores. Dataset is split into logical entities, each having dedicated API endpoint. Endpoints are accessible via HTTPS protocol. Data is returned in JSON format. Document schema and query parameters for each endpoint are described in this document.

API root lives at: https://integrations.apptopia.com All endpoint paths described below are given relative to this root URL.

Data Matrix

Ranked Apps

Please find below a detailed outline of all the different data points Apptopia gives you access to for “Ranked Apps”. Ranked Apps are defined as any app which has been ranked for at least one day, in any category / country within the iOS App Store or Google Play Store. Please note that whenever possible / available we will provide the greatest level of granularity. For instance, most data points below have country, store, and date specific granularity.

Meta Data Included:

• App Name
• AppID
• Category
• Subcategory
• Description
• File Size
• Price
• App URL
• In-App Purchases (yes or no)
• Total Ratings
• # of Reviews
• Review Text (additional fee)
• Initial Release date (iOS = back to inception, GP = back to 4/1/2014)
• Date of Last Update
• Version # (per update)
• “What’s New” text (per update)
• App Icon (image file or URL)
• Screenshots (image file or URL)
• Publisher Name
• PublisherID
• Publisher URL
• SDK Name
• SDK ID
• SDK URL
• SDK Function
• CommonID – App Level
• CommonID – Publisher Level
• CommonID – SDK Level
• Parent Company ID

App Performance Data Included:

• Overall Rank (as defined by store)
• Category Rank (as defined by store)
• Subcategory Rank (as defined by store)
• Downloads (estimate)
• Total Revenue (estimate)
• In App Purchase Revenue (estimate)
• Advertising Revenue (estimate) [deprecated]
• Paid Download Revenue (estimate)
• Average Revenue Per User (estimate)
• Daily Active Users (estimate)
• Monthly Active Users (estimate)
• Engagement % (estimate)
• 30 Day Retention (estimate)
• # of Sessions Per User (estimate)
• Total # of Sessions (estimate)
• Average Session Length Per User (estimate)
• Total Time Spent In App (estimate)
• Last 24hr Rank Change
• Breakout Likelihood % (predictive) [deprecated]

Publisher Performance Data Included:

• Downloads (estimate)
• Total Revenue (estimate)
• In App Purchase Revenue (estimate)
• Advertising Revenue (estimate) [deprecated]
• Paid Download Revenue (estimate)
• Average Revenue Per User (estimate)
• Daily Active Users (estimate)
• Monthly Active Users (estimate)
• Engagement % (estimate)
• Monetization Breakdown % (estimate)
• LinkedIn URL
• Web URL
• HQ Country

SDK Performance Data Included:

• App Level - SDKs Currently Installed
• App Level - Install Date
• App Level - SDKs Currently Uninstalled
• App Level - Uninstall Date
• App Level - If SDK is Being Used
• App Level - Date Last Seen Being Used
• App Level - List of API Endpoints
• SDK Vendor - Total # of SDK Installs
• SDK Vendor - Total # of SDK Uninstalls
• SDK Vendor - Total Installs Per Category
• SDK Breakout Data (i.e. dynamic installation counts on growing SDKs)

*  App Level = What SDKs Uber has installed
**   Vendor Level = Which apps have the Google Analytics SDK installed

Audience Data Included:

• % Male
• % Female
• Most Likely Age Of Users
• % Of Users 10-20 yrs. Old
• % Of Users 21-30 yrs. Old
• % Of Users 31-40 yrs. Old
• % Of Users 41-50 yrs. Old
• % Of Users 51+ yrs. old
• User Graph – i.e. an analysis off cross app usage – which gives you into what other apps users of App A, are also actively using and the Overlap % between those two apps.

All Apps

Please find below a detailed outline of all the different data points Apptopia gives you access to for “All Apps”. All Apps is defined as any app that is currently available for download in either the iOS App Store of Google Play Store. It does not matter if the app is ranked, has ever been downloaded, etc. Please note that whenever possible / available we will provide the greatest level of granularity. For instance, most data points below have country, store, and date specific granularity.

Data Included:

• App Name
• AppID
• Category
• Subcategory
• Description
• File Size
• Price
• App URL
• In-App Purchases (yes or no)
• Total Ratings
• # of Reviews
• Review Text
• Initial Release date (iOS = back to inception, GP = back to 4/1/2014)
• Date of Last Update
• Version # (per update)
• “What’s New” text (per update)
• App Icon (image file or URL)
• Screenshots (image file or URL)
• Publisher Name
• PublisherID
• Publisher URL
• Parent Company ID
• Interactive Elements

Authentication

Here's an example of access credentials:

  client: JFqXPDhiLuvY
  secret: L2nerprCksacBoFzUqtfHz8v

Session token is obtained via HTTPS POST request:

  curl -X "POST" "https://integrations.apptopia.com/api/login" \
       -H "Content-Type: application/x-www-form-urlencoded" \
       --data-urlencode "client=<client>" \
       --data-urlencode "secret=<secret>"

New session token is returned in JSON formatted response:

  {"token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJDbGllbnQ6MiIsImV4cCI6MTQ2NDI0ODU4MSwiaWF0IjoxNDYzMDM4OTgxLCJpc3MiOiJpbnRlZ3JhdGlvbnMuYXBwdG9waWEuY29tIiwianRpIjoiODM3NmQzODgtMzM3ZC00YjNjLTg1YTctMTZhNmU3OWI2YjI4IiwicGVtIjp7ImludGVncmF0aW9ucyI6MiwicmF3X2VuZHBvaW50cyI6MjU1fSwic3ViIjoiQ2xpZW50OjIiLCJ0eXAiOiJ0b2tlbiJ9.mVIR43675zXeudPTf-4q0vDuXpLAx0Suy8_KD2ZXjnX6HdN2xRJCmHP_6tnNzvWw78oNcSNae9s1yfE3Kolqbg"}

Session token can be used for subsequent requests until it expires. Default expiration interval is 2 weeks. Valid token should be present in Authorization header of all requests performed against Apptopia Data API:

  curl -X "GET" "https://integrations.apptopia.com/api/itunes_connect/app?id[]=1091944550&id[]=946659216&id[]=327630330" \
       -H "Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJDbGllbnQ6MiIsImV4cCI6MTQ2NDI0ODU4MSwiaWF0IjoxNDYzMDM4OTgxLCJpc3MiOiJpbnRlZ3JhdGlvbnMuYXBwdG9waWEuY29tIiwianRpIjoiODM3NmQzODgtMzM3ZC00YjNjLTg1YTctMTZhNmU3OWI2YjI4IiwicGVtIjp7ImludGVncmF0aW9ucyI6MiwicmF3X2VuZHBvaW50cyI6MjU1fSwic3ViIjoiQ2xpZW50OjIiLCJ0eXAiOiJ0b2tlbiJ9.mVIR43675zXeudPTf-4q0vDuXpLAx0Suy8_KD2ZXjnX6HdN2xRJCmHP_6tnNzvWw78oNcSNae9s1yfE3Kolqbg"

In order to make requests against Data API, client needs to perform authentication. We use JSON Web Tokens method of authentication (https://jwt.io). In order to obtain auth token, client submits credentials to /api/login endpoint.

Credentials are provided by Apptopia as part of Data API signup process.

All examples below use <token> placeholder for brevity.

Limits

There's limit on request rate which client may generate. When client exceeds this limit, API responds with 429 "Too Many Requests" response. Suggested strategy for handling such responses is retrying with exponential backoff. Also, there are some common limits on query parameters shared across number of endpoints.

• Max request rate: 1000 requests/minute
• Max time series interval length for single request: 180 days
• Max number of ids in single request for lookup endpoints: 50

Conventions on IDs

For iTunes App Store, apps are referenced by ids which are exposed by web version of the App Store (https://itunes.apple.com), e.g. the app "Candy Crush Saga" by publisher King can be found by url https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8 Apptopia Data API uses the same id 553834731 for this app internally.

iTunes publishers also have publicly visible ids. King's app store page can be found by url https://itunes.apple.com/us/developer/king/id526656015 Similarly to apps, Apptopia uses id 526656015 for referencing this publisher across Data API.

Google Play apps use text ids. The same app "Candy Crush Saga" has the following Google Play page: https://play.google.com/store/apps/details?id=com.king.candycrushsaga This app is referenced across the Data API by id "com.king.candycrushsaga".

Xiaomi, Mobile 360 and Tencent Store apps use text ids, similar to Google Play. The "全民斗战神" app has the following Tencent page: http://android.app.qq.com/myapp/detail.htm?apkName=com.tencent.tmgp.asura This app is references across the Data API by id "com.tencent.tmgp.asura".

Apptopia uses internal numeric surrogate ids for Google Play publishers and SDKs in all stores.

API Endpoints

Overview

Here's the list of all supported endpoints:

Here, :store is a placeholder for store name, which can be either of google_play, itunes_connect, xiaomi, mobile_360 or tencent. Endpoints have different requirements for query parameters, however there are three distinct access patterns shared across the list:

• Directory lookup. Countries and categories fall into this pattern. Query doesn't require any parameters and response contains full collection of entities.

• Discovery API. Used for large data sets in order to iterate through all its elements. Full data set is broken down into roughly equal segments. Each of such segments then can be paged through in concurrently.

• Id lookup. Key-value type of data API, where entities are accessed by their ids. Apps and publishers are examples of this pattern.

• Time series lookup. Query specifies entity and date range, response contains all available data for requested entity within date range. Examples are estimates and ranks time series.

Directory Endpoints

GET request to these endpoints without any query parameters yields response with JSON encoded collection, e.g. for country list:

  curl -X "GET" https://integrations.apptopia.com/api/countries" -H "Authorization: <token>"

Supported countries and app store category id lists are available via:

• /api/countries
• /api/:store/categories
• /api/tags

Discovery Endpoints

Consider the following example:

  curl -X "GET" "https://integrations.apptopia.com/api/itunes_connect/app/discovery?partition=1&total_partitions=1000" \
       -H "Authorization: <token>"

Response contains the following JSON data (output is reduced):

  {
    "result_rows": [
      {
        "publisher_url": "http://www.tomsoft.co.uk/iphone/iphone-design.htm",
        "offers_in_app_purchases": false,
        "price_cents": 99,
        "name": "Packing ~ for holiday and business",
        "category_name": "Travel",
        "publisher_id": 286879564,
        "id": 366691344,
        "subcategory_name": "Lifestyle",
        "last_update_date": "2010-04-16",
        "publisher_name": "Hurryforward Ltd",
        "subcategory_id": 6012,
        "category_id": 6003,
        "app_store_url": "https://itunes.apple.com/us/app/packing-for-holiday-business/id366691344?mt=8"
      },
      ...
    ],
    "next_page_token": "0022001000043d2a5f2c00160013766e645f7372635f636f756e7472795f69736f007ffffe0b78943bbada15c6dee72a47f3059ea7410002"
  }

Here, result_rows array contains up to 500 records, and next_page_token holds value for fetching the next page of partition 1:

  curl -X "GET" "https://integrations.apptopia.com/api/itunes_connect/app/discovery?partition=1&total_partitions=1000&page_token=0022001000043d2a5f2c00160013766e645f7372635f636f756e7472795f69736f007ffffe0b78943bbada15c6dee72a47f3059ea7410002" \
       -H "Authorization: <token>"

Discovery endpoints are used for iterating through all elements of corresponding dataset. Here's the list of all discovery endpoints:

• /api/parent_company/discovery
• /api/:store/app/discovery
• /api/:store/publisher/discovery
• /api/:store/sdk/discovery
• /api/:store/app_sdks/discovery

All discovery endpoints share the same query format:

• total_partitions - integer value between 100 and 10000. It specifies number of partitions by which full dataset is split. Partitions can be iterated concurrently. Each individual partition is paged through sequentially. All requests of single discovery attempt should have the same total_partitions value to ensure consistent results.

• partition - integer value from 1 to total_partitions, specifies partition being paged through

• page_token - opaque string. Paging through given partition is performed by iterating over page_token values. Request for the first page of a partition is done without page_token. Each response of discovery API contains next_page_token value, except for the last page of a partition. This value should be used for the next page request of the same partition. Iteration ends when discovery response doesn't contain next_page_token, denoting the last page. Note that page tokens can't be used across partitions.

Time Series Endpoints

Multiple apps time series can be fetched at once by submitting array of id[] parameters. Here's example query which pulls performance metrics for Facebook and Facebook Messenger in US within 4/20/2016 to 4/30/2016 for Google Play store:

  curl -g -X "GET" "https://integrations.apptopia.com/api/google_play/estimates?id[]=com.facebook.katana&id[]=com.facebook.orca&date_from=2016-04-20&date_to=2016-04-30&country_iso=US" \
       -H "Authorization: <token>"

Endpoints return JSON encoded list of matching results:

  [
    {
      "engagement": 0.6374,
      "downloads": 64083,
      "date": "2016-04-20",
      "iap_revenue": 0.0,
      "country_iso": "US",
      "mau": 232027956,
      "total_revenue": 0.0,
      "download_revenue": 0.0,
      "dau": 147883883,
      "arpu": 0.0,
      "id": "com.facebook.katana"
    },
    ...
    {
      "engagement": 0.7187,
      "downloads": 89178,
      "date": "2016-04-20",
      "iap_revenue": 0.0,
      "country_iso": "US",
      "mau": 130750310,
      "total_revenue": 0.0,
      "download_revenue": 0.0,
      "dau": 93964174,
      "arpu": 0.0,
      "id": "com.facebook.orca"
    },
    ...
  ]

Number of performance metrics are represented as time series. Endpoints which serve time series date are:

• /api/:store/app_ranks
• /api/:store/ratings
• /api/:store/estimates
• /api/:store/app_sessions
• /api/:store/publisher_estimates
• /api/:store/sdk_category_performance

Query parameters:

Time Series Discovery Endpoints

Responses of /api/app_estimates/discovery and /api/publisher_estimates/discovery will include rows for all stores, and rows will be grouped:

  curl -X "GET" "https://integrations.apptopia.com/api/app_estimates/discovery?partition=1&total_partitions=1000&date_from=2016-06-10&date_to=2016-08-10" \
       -H "Authorization : <token>"

... will give result with the following form:

  {"result_rows": {
    "itunes_connect": [
      {"date": ..., "id": ..., "country_iso": ..., "engagement": ...,"downloads": ..., ...},
      {"date": ..., "id": ..., "country_iso": ..., "engagement": ...,"downloads": ..., ...},
      ...],
    "google_play": [
      {"date": ..., "id": ..., "country_iso": ..., "engagement": ...,"downloads": ..., ...},
      {"date": ..., "id": ..., "country_iso": ..., "engagement": ...,"downloads": ..., ...},
      ...]},
  "next_page_token": ....}

TS discovery endpoints are suited for bulk data ingestion. Typical use case for such endpoints is retrieving dump of all rows within certain date range for all apps/countries/stores. Here's the list of all time series discovery endpoints:

• /api/app_estimates/discovery
• /api/app_sessions/discovery
• /api/publisher_estimates/discovery
• /api/:store/ratings/discovery

TS discovery endpoints should be used similarly to plain discovery endpoints described above. Iteration is performed through pages within independent partitions. The only additional requirement is that queries should include date_from and date_to query parameters. Max allowed date range for theese parameters is 180 days. If more than 180 days of data is needed, it should be pulled in chunks.

Entity Lookup Endpoints

Here's an example query which fetches data for 3 publishers: Mojang and Ndemic Creations:

  curl -g -X "GET" "https://integrations.apptopia.com/api/itunes_connect/publisher?id[]=479516146&id[]=525818842" \
          -H "Authorization: <token>"

Response JSON contains array of documents:

  [
    {
      "id": 479516146,
      "name": "Mojang",
      "app_ids": [479516143],
      "other_stores": [{"store": "google_play", "id": 1148}],
      "contacts": {
        "company": {
          "address": "",
          "email": null,
          "logo_url": "https://www.crunchbase.com/organization/mojang/primary-image/raw",
          "employee_count": "51-100",
          "profile_image_url": "http://public.crunchbase.com/t_api_images/v1397196646/f7b513ca2ad52df359c123d501c78f07.png",
          "phone": "46 8 50 16 42 25",
          "city": "Stockholm",
          "zipcode": null,
          "facebook_url": "https://www.facebook.com/minecraft",
          "short_description": "Mojang is a Swedish game developer creating independent video games such as Minecraft.",
          "company_name": "Mojang",
          "region": "Stockholm",
          "country_code": "SWE",
          "categories": ["developer platform", "gaming", "video games"],
          "closed_on": null,
          "status": "acquired",
          "primary_role": "company",
          "twitter_url": "https://www.twitter.com/mojangteam",
          "linkedin_url": "https://www.linkedin.com/company/1666639",
          "homepage_url": "http://mojang.com",
          "cb_url": "https://www.crunchbase.com/organization/mojang",
          "domain": "mojang.com",
          "category_groups": ["gaming", "software"],
          "founded_on": "2010-01-01T05:00:00Z",
          "state_code": null
        },
        "employees": [
          {
            "first_name": "Carl",
            "logo_url": null,
            "profile_image_url": null,
            "facebook_url": null,
            "country_code": null,
            "primary_affiliation_title": "Founder & Managing Director",
            "twitter_url": null,
            "last_name": "Manneh",
            "linkedin_url": "https://se.linkedin.com/in/carlmanneh",
            "cb_url": null,
            "gender": null,
            "emails": ["carl@mojang.com"],
            "state_code": null,
            "primary_affiliation_organization": null
          },
          ...
        ]
      },
      "profile_url": "https://www.linkedin.com/company/mojang-ab",
      "website_url": "http://mojang.com",
      "hq_country": "Sweden"
    },
    {
      "id": 525818842,
      "name": "Ndemic Creations",
      "app_ids": [1124500826, 525818839],
      "other_stores": [],
      "contacts": {
        "company": {
          "address": "",
          "email": null,
          "logo_url": null,
          "employee_count": "1-10",
          "profile_image_url": null,
          "phone": null,
          "city": "London",
          "zipcode": null,
          "facebook_url": "http://www.facebook.com/plagueinc",
          "short_description": "Ndemic Creations is a mobile apps developer company and has developed a game named Plague Inc.",
          "company_name": "Ndemic Creations",
          "region": "London",
          "country_code": "GBR",
          "categories": null,
          "closed_on": null,
          "status": "operating",
          "primary_role": "company",
          "twitter_url": "https://www.twitter.com/ndemiccreations",
          "linkedin_url": "https://www.linkedin.com/company/3066047",
          "homepage_url": "http://www.ndemiccreations.com",
          "cb_url": "https://www.crunchbase.com/organization/ndemic-creations",
          "domain": "ndemiccreations.com",
          "category_groups": null,
          "founded_on": "2011-01-01T05:00:00Z",
          "state_code": null
        },
        "employees": [
          {
            "first_name": "James",
            "logo_url": null,
            "profile_image_url": null,
            "facebook_url": null,
            "country_code": null,
            "primary_affiliation_title": "CEO & Founder",
            "twitter_url": null,
            "last_name": "Vaughan",
            "linkedin_url": "https://uk.linkedin.com/in/jamesvaughan1",
            "cb_url": null,
            "gender": null,
            "emails": [
              "james.vaughan@ndemiccreations.com"
            ],
            "state_code": null,
            "primary_affiliation_organization": null
          },
          ...
        ]
      },
      "profile_url": "https://www.linkedin.com/company/ndemic-creations",
      "website_url": "http://www.ndemiccreations.com",
      "hq_country": null
    }
  ]

The following endpoints return documents by id:

• /api/:store/app
• /api/:store/app_versions
• /api/:store/app_sdks
• /api/:store/app_files
• /api/:store/publisher
• /api/:store/sdk
• /api/:store/app_ads_txt
• /api/:store/pub_ads_txt

Query should provide either single id parameter or multiple id[] parameters. Number of documents that can be fetched with single query is limited by 50.

Store Top Charts

Consider the example request for iOS Overall free ranks in US on 4/29/2015:

  curl -X "GET" "https://integrations.apptopia.com/api/itunes_connect/rank_lists?id=36&date=2015-04-29&kind=free&country_iso=US" \
       -H "Authorization: <token>"

Example response:

  [
    {
      "date": "2015-04-29",
      "country_iso": "US",
      "kind": "free",
      "category_id": 36,
      "app_ids": [
        454638411,
        284882215,
        389801252,
        ...
      ]
    }
  ]

Top charts are represented by arrays of app ids. Apps are ordered from top to bottom: from rank 1 to the lowest available rank.

Endpoint path: /api/:store/rank_lists

Query parameters:

Featured Apps

In order to pull list of apps featured in list "Games We Love" present on the root page of iTunes App Store, the following query can be used:

  curl -X "GET" "https://integrations.apptopia.com/api/itunes_connect/featured_lists?date=2016-05-19&category_id=36&country_iso=US&list_name_in_us=New+Games+We+Love"
       -H "Authorization: <token>"

Example response:

[
  {
    "name": "New Games We Love",
    "app_ids": [
      1075872386,
      1031706898,
      1079464948,
      1083451870,
      974135847,
      1108384425,
      1071426243,
      1044953131,
      1057415521,
      1096204046,
      1022239163,
      1084252650,
      1071511733,
      1084600612,
      1084135698,
      1087282720
    ]
  }
]

Data on featured apps is returned in form of id lists, similarly to rank top charts.

Featured apps endpoint path: /api/:store/featured_lists

Query parameters:

Root page of an app store can be referenced by Overall category id (store specific).

App daily rank change

In order to pull Pokémon GO rank change in Finland on 2016-08-09, the following query can be used:

curl -X "GET" "https://integrations.apptopia.com/api/itunes_connect/app_daily_rank_change?id%5B%5D=1094591345&date=2016-07-14&country_iso=US" \
   -H "Authorization : <token>"

Example response:

[
  {
    "id": 1094591345,
    "country_iso": "US",
    "date": "2016-08-09",
    "kind": "free",
    "rank_change": 0,
    "category_id": 36
  },
  {
    "id": 1094591345,
    "country_iso": "US",
    "date": "2016-08-09",
    "kind": "free",
    "rank_change": 0,
    "category_id": 6014
  }
]

Data on app's rank change on given date in all categories and rank kinds it is ranked.

Endpoint path: /api/:store/app_daily_rank_chage

Query parameters:

App New releases

In order to pull new Games released between 2016-08-03 and 2016-08-04 in US, the following can be used:

curl -X "GET" "https://integrations.apptopia.com/api/itunes_connect/new_releases?date_from=2016-08-03&date_to=2016-08-04&country_iso=US&category_id=6014&attrs%5B%5D=id" \
   -H "Authorization : <token>"

Data on new app releases in a time period within last 30 days.

Endpoint path: /api/:store/new_releases

Query parameters:

The response is formatted by the same rules as in App endpoint.

App Graph (Cross App Usage)

Weighted connection between apps based reviews data. It is not meant to tell you the exact # of users who use both apps, but rather is meant to be used to understand proportions. For instance If App A and B had an weight_sim value of .80 and App A and App C had a value of 0.2, you could confidently assume that users of App A are 4x more likely to also be active users of App B versus App C.

Endpoint path: /api/:store/app_graph

Query parameters:

Response fields:

This dataset is being updated on a monthly basis, hence only year and month parts of a date date value are being used to address a requested dataset. Pulling data for different dates within the same month will result in identical responses.

In order to pull Instagram iTunes Cross App Usage for June 2020 in US, the following can be used:

curl -X "GET" "https://integrations.apptopia.com/api/itunes_connect/app_graph?id=389801252&date=2020-05-01&country_iso=US" \
     -H 'Authorization: <token>'

Discovery Endpoint for App Graph /api/:store/app_graph/discovery takes the same partition parameters as other discovery endpoints.

Discovery Endpoint also includes query parameters:

InApp Purchases

Returns a list of json records in the following format:

curl -X "GET" "https://integrations.apptopia.com/api/itunes_connect/inapp_purchases?&country_iso=US&date_from=2022-01-01&date_to=2022-06-01&id=389801252" \
   -H "Authorization : <token>"

[
  {
    "country_iso":"US",
    "date":"2022-01-04",
    "app_id":389801252,
    "name":"Instagram Badge",
    "price":"$4.99"
  },
  {
    "country_iso":"US",
    "date":"2022-01-04",
    "app_id":389801252,
    "name":"Instagram Badge",
    "price":"$0.99"
  },
  {
    "country_iso":"US",
    "date":"2022-01-04",
    "app_id":389801252,
    "name":"Instagram Badge",
    "price":"$1.99"
  }
]

InApp purchases data.

Endpoint path: /api/:store/inapp_purchases

Query parameters:

App Retention

App retention data.

Endpoint path: /api/:store/app_retention

Query parameters:

This dataset is being updated on a monthly basis, hence only year and month parts of a date date value are being used to address a requested dataset. Pulling data for different dates within the same month will result in identical responses.

Discovery Endpoint for App Retention /api/:store/app_retention/discovery takes the same partition parameters as other discovery endpoints.

Discovery Endpoint also includes query parameters:

Category Retention

Category retention data.

Endpoint path: /api/:store/category_retention

Query parameters:

This dataset is being updated on a monthly basis, hence only year and month parts of a date date value are being used to address a requested dataset. Pulling data for different dates within the same month will result in identical responses.

Discovery Endpoint for Category Retention /api/:store/category_retention/discovery takes the same partition parameters as other discovery endpoints.

App Demographics Data

App demographics data.

Endpoint path: /api/:store/app_demographics

Query parameters:

This dataset is being updated on a monthly basis, hence only year and month parts of a date date value are being used to address a requested dataset. Pulling data for different dates within the same month will result in identical responses.

Discovery Endpoint for App Demographics /api/:store/app_demographics/discovery takes the same partition parameters as other discovery endpoints.

App ads.txt Data

Returns a list of App's AD domain records in the following format:

[
  {
    "status": "success",
    "domain": "zynga.com",
    "refreshed_at": "2019-09-02T13:13:40.000-00:00",
    "app_id": "com.zynga.livepoker",
    "records": [
       {
         "field_ad_domain": "inmobi.com",
         "field_pub_id": "00833f99fc084044a48e28282e332668",
         "field_type": "DIRECT",
         "field_authority": "83e75a7ae333ca9d"
       },
       {
         "field_ad_domain": "inmobi.com",
         "field_pub_id": "571",
         "field_type": "DIRECT",
         "field_authority": "83e75a7ae333ca9d"
       },
       {"field_ad_domain": "rubiconproject.com",
        "field_pub_id": "11726",
        "field_type": "RESELLER",
        "field_authority": "0bfd66d529a55807"
       },
       ...
    ]
  }
]

App ads.txt data.

Endpoint path: /api/:store/app_ads_txt

Query parameters:

Publisher ads.txt Data

Returns a list of Publisher's AD domain records in the following format:

[
  {
    "status": "success",
    "domain": "zynga.com",
    "refreshed_at": "2019-09-02T13:13:40Z",
    "records": [
      {
        "field_ad_domain": "inmobi.com",
        "field_pub_id": "00833f99fc084044a48e28282e332668",
        "field_type": "DIRECT",
        "field_authority": "83e75a7ae333ca9d"
      },
      {
        "field_ad_domain": "inmobi.com",
        "field_pub_id": "571",
        "field_type": "DIRECT",
        "field_authority": "83e75a7ae333ca9d"
      },
      {
        "field_ad_domain": "rubiconproject.com",
        "field_pub_id": "11726",
        "field_type": "RESELLER",
        "field_authority": "0bfd66d529a55807"
      },
      ...
    ]
  }
]

Publisher ads.txt data.

Endpoint path: /api/:store/pub_ads_txt

Top Advertisers

Returns a list of Advertising apps in all categories and all AD networks in WW in the following format:

[
  {
    "id": "com.spotify.music",

    // Store from the request
    "store": "google_play",

    // Rank is calculated the same way as on apptopia.com.
    "rank": 1,

    // Date of measurement in ISO 8601 format
    "date": "2019-10-18",

    // Country code
    "country_iso": "WW",

    // Ad network sdk ids assigned to this application
    "ad_network_sdk_ids": [100, 101, ...],

    // Last time ad was seen for the current applicatioin in ISO 8601 format
    "last_ad_seen": "2019-10-01",

    // Current publisher ID of the application
    "publisher_id": 10,
  ...
]

Endpoint path: /api/:store/acquisition/top_advertisers

Query parameters:

Top Ad Publishers

Returns a list of Publishing apps in all categories and all AD networks in the following format:

[
  {
    "id": 1009442510,

    // Store from the request
    "store": "google_play",

    // Rank is calculated the same way as on apptopia.com.
    "rank": 1,

    // Date of measurement in ISO 8601 format
    "date": "2019-10-18",

    // Country code from the request
    "country_iso": "WW",

    // Ad network sdk ids assigned to this application
    "ad_network_sdk_ids": [100, 101, ...],

    // Current publisher ID of the application
    "publisher_id": 10,
    ....
  },
  ...
]

Endpoint path: /api/:store/acquisition/top_publishers

Query parameters:

Reviews summary

Returns a list of reviews summary per app for the requested period and reviews data for each day per app in the following format:

{
  "summary": [
    {
      // Analyzed reviews for app for the period
      "analyzed_reviews": 264743,
      // Overall sentiment for the period
      "overall_sentiment": 46.47,
      // Number of sentiments for the priod
      "sentiments": {
        "positive": 35832,
        "negative": 48011,
        "mixed": 713,
        "neutral": 20643
      },
      // Intents for the priod
      "intents": {
        "service": 8102,
        "performance_and_bugs": 12196,
        "payment": 5197,
        "support": 6372,
        "login": 6584,
        "feature_request": 1752,
        "notifications": 745,
        "design": 6149
      },
      // App id
      "app_id": "com.instagram.android"
    },
    ...
  ],
  "time_series" : [
    {
      // Number of analyzed reviews for the given date
      "analyzed_reviews": 25059,
      // Overall sentiment for date
      "overall_sentiment": 65.18,
      // Number of sentiments for date
      "sentiments": {
        "positive": 3520,
        "negative": 3204,
        "mixed": 72,
        "neutral": 1776
      },
      "intents": {
        "service": 668,
        "performance_and_bugs": 1298,
        "payment": 418,
        "support": 623,
        "login": 656,
        "feature_request": 177,
        "notifications": 80,
        "design": 499
      },
      "app_id": "com.instagram.android",
      // Date of the calculations
      "date": "2021-05-13"
    },
    ...
  ]
}

Endpoint path: /api/:store/reviews/summary

Query parameters:

Tag Library

Sample curl request:

  curl -X "GET" "https://integrations.apptopia.com/api/tags?id[]=in-app-purchase&id[]=tournaments" \
       -H "Authorization: <token>"

Returns a list of tags in the following format:

[
  {
    "id": "in_app_purchase",
    "types": {
      "games": "monetization",
      "non-games": "monetization"
    },
    "name": "In-App-Purchase",
    "status": "DEPRECATED",
    "category": "both",
    "description": "In-app-purchase (IAP) revenue is collected by the store (iTunes/Google Play) and remitted to the publisher"
  },
  {
    "id": "tournaments",
    "types": {
      "games": "game feature"
    },
    "name": "Tournaments",
    "status": "APPROVED",
    "category": "games",
    "description": "Time or event-based competitions within the game."
  }
]

Returns our library of X-Ray tags with tag_id, tag_name, description, status, and what category of apps it applies to (games, non-games, both).

Endpoint path: /api/tags

Query parameters:

Bulk Data Exports

This endpoint gives access to daily dumps of:

• Apps Meta Data
• Publishers Meta Data
• SDKs Meta Data
• App Installed SDKs
• App Performance Estimates
• App Retention Estimates
• App Sessions Estimates
• App Ratings
• Cross App Usage
• Publisher Performance Estimates

Endpoint path: /api/:store/data_dumps

Query parameters:

Supported dataset slugs:

The interval parameter sets the length of a time span covered by data export:

• day - requests for a single day dumps, marked with the date of the day's dump
• month - requests for monthly dumps, each holding a whole month worth of data, where each dump will be marked with the date of the beginnig of the month, e.g. "2017-03-01" for March 2017
• quarter - requests for quarterly dumps, each holding a whole quarter of a year, where each dump will be marked with the date of the beginnig of the quarter, e.g. "2017-04-01" for 2017 Q2.

In order to pull daily App Estimates for a time span from 2017-02-20 to 2017-02-21 the following query can be used:

curl "https://integrations.apptopia.com/api/itunes_connect/data_dumps?dataset=daily_app_estimates&date_from=2017-02-20&date_to=2017-02-21&interval=day" \
     -H "Authorization : <token>"

API response will return a list of URLs which can be used to download dataset dump parts:

[
  {
    "date": "2017-02-20",
    "part": 0,
    "url": "https://apptopia-bulk.s3.amazonaws.com/itunes_connect/daily_app_estimates/v1.1/2017-02-20/494e4070-f886-11e6-b542-192190c5b33f/part-00000?AWSAccessKeyId=AKIAICBZB6INWPXQ757Q&Expires=1487837775&Signature=uTh0XjJwi7B8Y7ZoqvtUG97DEgs%3D"
  },
  {
    "date": "2017-02-20",
    "part": 1,
    "url": "https://apptopia-bulk.s3.amazonaws.com/itunes_connect/daily_app_estimates/v1.1/2017-02-20/494e4070-f886-11e6-b542-192190c5b33f/part-00001?AWSAccessKeyId=AKIAICBZB6INWPXQ757Q&Expires=1487837775&Signature=wseJmYN1oArM4491jAyfUKaPGNc%3D"
  },
  ...
]

URLs are valid within 24h since the API query invocation.

In order to pull two first monthly dumps of the year 2017 the following query can be used:

curl "https://integrations.apptopia.com/api/itunes_connect/data_dumps?date_from=2017-01-01&dataset=daily_app_estimates&date_to=2017-02-01&interval=month" \
     -H "Authorization : <token>"

Please note that time span 2017-01-01 to 2017-02-01 here works because January and February are marked 2017-01-01 and 2017-02-01 respectively, which fits in provided time span.

In order to pull 2016 Q1 and Q2 dumps, the following query can be used:

curl "https://integrations.apptopia.com/api/itunes_connect/data_dumps?dataset=daily_app_estimates&date_from=2016-01-01&interval=quarter&date_to=2016-05-01" \
     -H "Authorization : <token>"

Same as with monthly data, the 2016-01-01 to 2016-05-01 time span here works, because Q1 and Q2 are marked 2016-01-01 and 2016-04-01 respectively, which fits in provided time span.

Monthly and quarterly dumps responses are following the same structure as the daily ones.

Data format in part files is the same as in the corresponding ad-hoc endpoint, e.g. /api/:store/app for Apps dataset.

Custom Data Reports

This endpoint provides access to custom data reports:

Endpoint path: /api/:store/custom_reports

Supported store values:

Query parameters:

In order to pull data for report with id "66d98e90-a782-43ec-adce-3a2ac9beb5bd" for 'Google Play' store for a time span from 2020-02-15 to 2020-02-17 the following query can be used:

curl "https://integrations.apptopia.com/api/google_play/custom_reports?report_id=66d98e90-a782-43ec-adce-3a2ac9beb5bd&date_from=2020-02-15&date_to=2020-02-17" \
     -H "Authorization : <token>"

API response will return a list of URLs which can be used to download dataset dump parts:

[
  {
    "url":"https://integrations.apptopia.com/dataset/66d98e90-a782-43ec-adce-3a2ac9beb5bd/apptopia-custom-reports/google_play/2020-02-15/part-00000.json.gz?X-Amz-Date=20200219T101027Z&X-Amz-Expires=86400&X-Amz-Signature=db44a773532436940f206cd21e46ca58ce83cdb2a7dfefed7351aeb5b762aca6&X-Amz-SignedHeaders=host"
  },
  {
    "url":"https://integrations.apptopia.com/dataset/66d98e90-a782-43ec-adce-3a2ac9beb5bd/apptopia-custom-reports/google_play/2020-02-16/part-00000.json.gz?X-Amz-Date=20200219T101027Z&X-Amz-Expires=86400&X-Amz-Signature=db44a773532436940f206cd21e46ca58ce83cdb2a7dfefed7351aeb5b762aca6&X-Amz-SignedHeaders=host"
  },
  {
    "url":"https://integrations.apptopia.com/dataset/66d98e90-a782-43ec-adce-3a2ac9beb5bd/apptopia-custom-reports/google_play/2020-02-17/part-00000.json.gz?X-Amz-Date=20200219T101027Z&X-Amz-Expires=86400&X-Amz-Signature=db44a773532436940f206cd21e46ca58ce83cdb2a7dfefed7351aeb5b762aca6&X-Amz-SignedHeaders=host"
  },
  ...
]

URLs are valid within 24h since the API query invocation.

Attributes

Parent Companies

Apps

App ids are app store specific, Apple App Store exposes numeric ids, e.g. "553834731" for Candy Crush Saga. Google Play uses app package names for ids, e.g. "com.king.candycrushsaga" for the same app.

Dates are strings in ISO-8601 format, i.e.: "YYYY-MM-DD".

App Versions

App versions is lookup endpoint which returns full tracked app versions history for an app/country combination. Query keys are:

• id or ids - string or array of string, app ids
• country_iso - string, country ISO, (iTunes only attribute)

Returned attributes:

  "versions": [
    {
      "version": "1.2.3",
      "description": "bla",
      "date": "2016-01-01"
    },
    ....
  ]

Returned version records are sorted in chronological order.

App Ranks

App Ranks Summary

App Estimates

App Sessions

Publisher Estimates

Endpoint is similar to app estimates. It serves subset of app estimates attributes. Publisher metrics are aggregate of its apps metrics.

App Ratings

iTunes App Store specific attributes:

Note that Apple App Store exposes ratings on per country basis, and Google Play exposes only global ratings metrics. There's only one country_iso value for Google Play: "WW".

Tags

SDKs

App SDKs

App Tags

General Attributes

Tag attributes

SDK Category Performance

    {
      "6014": {"installs": 100},
      "6008": {"installs": 10}
    }

• total_performance - map of metrics, aggregate value across all categories for on date, e.g.: {"installs": 110}

App ads.txt Data

General attributes

AD domain record attributes

Publisher ads.txt Data

AD domain record attributes

Publishers

General attributes

Contacts attributes

Company attributes

Employee attributes

Featured Apps

Daily rank change

New Releases

Same as Apps.

Top Advertisers

General attributes

Top Publishers

General attributes

Search Endpoints

There are two search endpoints available, API supports searching for apps and publishers:

• /api/app_search
• /api/publisher_search
• /api/parent_company_search

Search is performed via POST request with JSON-encoded body. Request body contains search query composed of filter forms defined on attributes and a text search form called match. Valid search query should have match or filter forms, or both. Optional query parameters limit=X and offset=Y allow paging through results.

Match operation takes a set of strings as parameters. It selects app/publisher records which match any of the parameters.

Single string match example form:

  ["match", "instagram"]

Match example form with multiple strings:

  ["match", "kingdom", "batman"]

Filter parameter is an array of tuples (JSON arrays) of form: [<predicate> <attribute> <value>]:

  ["filter", [[">=", "sdk_count", 10], ["in", "sdk_ids", [10, 20, 30]]]]

filters are combined via logical AND.

If there's only one filter in a query, enclosing array can be omitted:

  ["filter", [">=", "sdk_count", 10]]

instead of:

  ["filter", [[">=", "sdk_count", 10]]]

However both forms are valid.

Filter predicates can be inverted via logical not, like so:

  ["filter", ["not", ["in", "sdk_ids", [10, 20, 30]]]]

Here is an example query searching for apps with names matching "kingdom" and "batman", where primary category is not 6014, approx downloads in last 30 days are greater than 100 and approx revenue in last 30 days is greater than 1000:

  [["match", "kingdom", "batman"],
   ["filter",
    [["not", ["=", "primary_category_id", 6014]],
     [">", "rev_tier_30d", 100],
     [">", "dls_tier_30d", 1000]]]]

Note how both filter and match forms are present. Here's the same example performed via curl command, with limit of 5 applied:

  curl -X "POST" "https://integrations.apptopia.com/api/app_search?limit=5" \
       -H "Authorization: <token>" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '[["match", "kingdom", "batman"],
            ["filter",
              [["not", ["=", "primary_category_id", 6014]],
              [">", "rev_tier_30d", 100],
              [">", "dls_tier_30d", 1000]]]]'

Responses will contain arrays of app or publisher ids, grouped by stores, e.g:

  {"app_ids":
    {
      "google_play":[
        "com.gameloft.android.ANMP.GloftDYHM","com.turner.cardwars2", ...],
      "itunes_connect":[
        438404619,1154895849,1117002117, ...]
    }
  }

Example of app search by "Interactive Elements"

["match",
  ["interactive_elements", "Digital Purchases"],
  ["interactive_elements", "Users Interact"],
  ["interactive_elements", "In-App Purchases"]]

Example of app search by store url

["match", 
  ["app_store_url", "https://apps.apple.com/us/app/nfl/id389781154"],
  ["app_store_url", "https://play.google.com/store/apps/details?id=com.gotv.nflgamecenter.us.lite"]]

There's predefined list of attributes of apps/publishers which can be used in filters. Each attribute has specific type. This type defines set of applicable filter predicates for a given attribute.

Available filter predicates are:

Applicable predicates based on attribute type:

Below is the list of apps attributes which can be used in search filters:

Publisher attributes which can be used in search filters:

Parent company attributes which can be used in search filters:

Publisher Matching

The Publisher Matching endpoint provides a way to match a publisher by some query attributes:

Endpoint path: /api/publisher_match

A JSON encoded query example of a request of making an attempt to match two publishers

[
  {
    "name":"Rackspace Technology",
    "domain":"www.rackspace.com",
    "email_domain":"rackspace.com",
    "linkedin_url":"https://www.linkedin.com/company/rackspace-technology/",
    "hq_country_iso2":"US"
  },
  {
    "name":"Gamaga",
    "domain":"http://www.gamaga.com",
    "email_domain":"gamaga.com"
  }
]

The same example performed via curl:

  curl -X "POST" "https://integrations.apptopia.com/api/publisher_match" \
       -H "Authorization: <token>" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '[{"name":"Rackspace Technology","domain":"www.rackspace.com","email_domain":"rackspace.com","linkedin_url":"https://www.linkedin.com/company/rackspace-technology/","hq_country_iso2":"US"},
            {"name":"Gamaga","domain":"http://www.gamaga.com","email_domain":"gamaga.com"}]'

The responses will contain an array of results per requested query sorted by the matching score, best first, e.g:

[
  {
    "query":{
      "name":"Rackspace Technology",
      "domain":"www.rackspace.com",
      "email_domain":"rackspace.com",
      "linkedin_url":"https://www.linkedin.com/company/rackspace-technology/",
      "hq_country_iso2":"US"
    },
    "result":[
      {
        "score":3.279260935143288,
        "matched_attributes":{
          "hq_country_iso2":"US",
          "name":"Rackspace Hosting",
          "email_domain":[
            "rackspace.com"
          ],
          "domain":"rackspace.com"
        },
        "publisher_data":{...}
      }
    ]
  },
  {
    "query":{
      "name":"Gamaga",
      "domain":"http://www.gamaga.com",
      "email_domain":"gamaga.com"
    },
    "result":[
      {
        "score":2.536036036036036,
        "matched_attributes":{
          "name":"Sociedad Gamers Making Games Limitada",
          "email_domain":[
            "gamaga.com"
          ],
          "domain":"gamaga.com"
        },
        "publisher_data":{...}
      },
      {
        "score":0.888888888888889,
        "matched_attributes":{
          "name":"GamaGame"
        },
        "publisher_data":{}
      },
      {
        "score":0.888888888888889,
        "matched_attributes":{
          "name":"Gamagame"
        },
        "publisher_data":{...}
      },
      {
        "score":0.7083333333333334,
        "matched_attributes":{
          "name":"gamagal.net"
        },
        "publisher_data":{...}
      }
    ]
  }
]

Example of publisher search by store url

["match", ["app_store_url", "https://play.google.com/store/apps/dev?id=7468190409947973272"]]

A request only can be performed as POST with JSON-encoded body as array of queries where a single query should request for a single publisher matching.

Supported query parameters:

The more attributes with correct data provided in query the higher is the likelihood of a correct match.

The result records attributes are

FAQ

What time frames can I pull with the API?

• Normal End Points = 2015 to Present
• Discovery End Points = 2015 to Present
• Data Dump = 2015 to Present daily. Quarterly and monthly are not currently available.

How do I properly set the quarterly date range?

When working with quarterly data, the API query date should be set to the first day of the quarter being pulled. Hence Q1/2016 would mean 2016-01-01, Q2/2016 — 2016-04-01 and so on.

Do you rate limit?

Yes.

• Max request rate: 1000 requests/minute (we maintain a sliding 60s window and are calculating amount of request made so far within that window. exceeding requests are rejected with HTTP code 429.)
• Max time series interval length for single request: 180 days
• Max number of ids in single request for lookup endpoints: 50

If you are accessing a normal end point or a discovery end point than you are able to run 1,000 queries per min (16 new queries per sec). If you are accessing data through the data dump the S3 serve is limited to pull "300 GETs per second." This is a universal limit. If you are experiencing slow contact time please contact Success@apptopia.com.

Can I run more than one query at a time?

Yes you can run queries concurrently.

How can I increase the speed of my downloads?

If you experiencing slow download time this could be due to your internet connection. We suggest leveraging Amazon EBS as a tool to increase your efficiency. Amazon EC2 instance in us-east zone to pull, narrow down and pack your data before pulling it to your own data centre. The instance type does not have to be expensive. Amazon EBS volumes could be used together with low-end EC2 instances in order to get additional disk space. Amazon S3 could be used for long term storage of processed files.

What if I only want a subset of the data I am pulling?

Need help building a custom solution? Not a problem. Our custom solution packages are priced

What is the difference between your discovery end points, data dumps, and your normal end points?

The ad-hoc or normal endpoints help you when you know exactly which Apps, Publishers, SDKs or other records you would like to access by id. The ‘discovery’ endpoints help when you need to fetch a full dataset (e.g. all Apps) or some portion of it (e.g App Estimates on given time period).

The data dump work the same as ‘discovery’ endpoints but provide pre- aggregated snapshots of data daily.

The search endpoints are giving access to App and Publisher indexes helping to make targeted searches.

The entity lookup endpoints like App, Publisher, SDK etc are pointing to mutable data

How large are the files from the data dump?

The files they are downloaded are partitioned into 15-25mb

What apps stores do I have access to?

All API clients have access to iTunes and the Google Play store.

When is your data updated?

Our data updates every morning at 2a est. We aggregate our time series data on previous day. The data dump is aggregated at by 9a est, we recommend pulling this data on or after 10a est.

Is there a limit to the number of Apps I can look up?

Yes, 50 per single request.

Is there a max date range I can pull?

Yes, 180 Days.

Can I pull queries based on the last time the data was updated?

You can pull this for for time series by using date_from and date_to combined with the discovery or bulk data end point to fetch the data points that fall with in your desired time. For the Last_Updated date for apps, it is best to pull the bulk data dump and filter desired time in the last_updated_date field and store the results that meet your requirement. Unfortunately you are not able to search this not for publishers or SDK.

I am getting an error while trying to log in.

The most common issue, besides incorrect credentials, is extra spaces in auth headers. There should be no spaces around = (equality sign) in client and secret clauses.

I am having an issues accessing new_releases.

Check your time range. New_Releases are only accessible for the last 30 days.

Where to find age restriction data?

/api/:store/app /api/:store/app/discovery

What time zone are the time stamps in?

Estimations will have a time stamp in the API. They will be in eastern standard time.

If I am experiencing a result different that what I expect what should I do?

When sending an issues to the Customer Success team please provide the following data:

1. A brief description of what you are trying to pull
2. A brief description of what you would like to accomplish
3. The expected out come from
4. The actual out come from your query
5. An example of the CURL that is resulting in an unexpected outcome