NAV

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:

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 Performance Data Included:

Publisher Performance Data Included:

SDK Performance Data Included:

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

Advertising Intelligence Data Included:

Ad Formats We Collect

Ad Networks Supported

Specific Data Points

Audience Data Included:

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:

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%5B%5D=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.

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:

Endpoint URL Description
/api/login authentication
/api/countries list of supported countries
/api/parent_company parent company metadata
/api/parent_company/discovery parent company metadata discovery
/api/:store/categories list of categories
/api/:store/app app metadata
/api/:store/app_versions per app versions history
/api/:store/app/discovery iteration over all apps
/api/:store/publisher publisher metadata
/api/:store/publisher/discovery iteration over all publishers
/api/:store/sdk SDK metadata
/api/:store/sdk/discovery iteration over all sdks
/api/:store/rank_lists raw rank top charts
/api/:store/app_sdks per app SDK metadata
/api/:store/app_files per app files data
/api/:store/sdk_category_performance SDK level, per category aggregate performance
/api/:store/app_ranks per app rank history
/api/:store/app_ranks_summary per app ranks summary
/api/:store/app_daily_rank_chage per app daily rank change
/api/:store/app_tags per app tag metadata
/api/:store/ratings per app ratings history
/api/:store/estimates per app performance data
/api/:store/app_sessions per app session data
/api/app_estimates/discovery discovery endpoint for app performance data
/api/app_sessions/discovery discovery endpoint for app session data
/api/publisher_estimates/discovery discovery endpoint for publisher performance data
/api/:store/ratings/discovery discovery endpoint for app ratings data
/api/:store/app_sdks/discovery discovery endpoint for app SDKs data
/api/:store/publisher_estimates per publisher performance data
/api/:store/featured_lists featured apps data
/api/:store/new_releases recently released apps
/api/app_search apps search endpoint
/api/publisher_search publishers search endpoint
/api/parent_company_search parent company search endpoint
/api/:store/app_graph app graph data
/api/:store/app_graph/discovery discovery endpoint for app graph data
/api/:store/app_demographics app demographics data
/api/:store/app_demographics/discovery discovery endpoint for app demographics data
/api/:store/app_retention app retention data
/api/:store/app_retention/discovery discovery endpoint for app retention data
/api/:store/category_retention category retention data
/api/:store/category_retention/discovery discovery endpoint for category retention data
/api/:store/acquisition/top_advertisers top advertisers
/api/:store/acquisition/top_publishers top ad publishers
/api/:store/reviews/summary reviews summary data
/api/:store/app_ads_txt app ads.txt data
/api/:store/pub_ads_txt publisher ads.txt data

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 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:

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:

All discovery endpoints share the same query format:

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:

Query parameters:

Param Description
id store specific app id
country_iso string, ISO 3166 A2 country code
model_version optional string, either v2.0 (default) or v3.0

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:

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:

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:

Param Description
id int, store specific category id
date string date in iso8601 format, e.g. "2016-05-12"
country_iso string, ISO 3166 A2 country code
kind string, chart kind: "free", "paid" or "grossing"

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:

Param Description
date string, ISO 8601 date
country_iso string, ISO 3166 A2 country code
list_name_in_us optional string, name of featured list, as it appears in US store; when not present - returns all lists matching other parameters
match_type string, can be any of: eq, regexp, defines how list_name_in_us is used for string matching. Optional, default value is eq
category_id integer, store specific category id, referencing store category page on which featured list appears

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:

Param Description
date string, ISO 8601 date
country_iso string, ISO 3166 A2 country code
id store specific app id

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:

Param Description
country_iso string, ISO 3166 A2 country code
category_id integer, store specific category id
date_from string date in ISO 8601 format, start of date range, e.g. 2016-05-10
date_to string date in ISO 8601 format, end of date range, e.g. 2016-05-20

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:

Param Description
id store specific app id
date date in ISO 8601 format for which to find app graph data
country_iso two digit country codes in ISO 3166-1 format (itunes_connect) OR two digit language codes in ISO 639-1 format (google_play)

Response fields:

Field Description
weight (legacy calculation)
weight_sim Calculated by dividing the [Total Overlaps between App A and App B] / [ Total Possible Overlaps...i.e. total reviews of App B]. This is important as this is the reason you don't see Facebook & Google Maps at the top of every Cross App Usage chart. Instead the above Weight highlights the strongest cross app usage based on size and relevancy. This value matches the value displayed in the Apptopia web tool.

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:

Param Description
from optional date in ISO 8601 format
to optional date in ISO 8601 format

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:

Param Description
id store specific app id
date_from date in ISO 8601 format
date_to date in ISO 8601 format
country_iso Country ISO code

App Retention

App retention data.

Endpoint path: /api/:store/app_retention

Query parameters:

Param Description
id store specific app id
date date in ISO 8601 format
country_iso Country ISO code

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:

Param Description
from optional date in ISO 8601 format
to optional date in ISO 8601 format

Category Retention

Category retention data.

Endpoint path: /api/:store/category_retention

Query parameters:

Param Description
id store specific category id
date date in ISO 8601 format
country_iso Country ISO code

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:

Param Description
id store specific app id
date date in ISO 8601 format
country_iso Country ISO code

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:

Param Description
id store specific app id

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

Param Description
id store specific publisher id

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:

Param Description
date string date in ISO 8601 format, day of measurement, e.g. 2019-10-18
limit optional integer value between 1 and 10000, specifies the number of apps returned, defaults to 1000

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:

Param Description
date string date in ISO 8601 format, day of measurement, e.g. 2019-10-18
country_iso string, 2 alpha country code according Alpha-2 ISO-3166, e.g. US (WW for all countries)
limit optional integer value between 1 and 10000, specifies the number of apps returned, defaults to 1000

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:

Param Description
id store specific app id(s)
date_from string date in ISO 8601 format, start of date range, e.g. 2018-07-01
date_to string date in ISO 8601 format, end of date range, e.g. 2018-07-02 (should be at least 10 days in the past from today's date)

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:

Param Description
id string, optional tag id. Multiple tags can be fetched at once by submitting array of id[] parameters. When no id is provided, returns all available tags.

Bulk Data Exports

This endpoint gives access to daily dumps of:

Endpoint path: /api/:store/data_dumps

Query parameters:

Param Description
model_version optional string, either v2.0 (default) or v3.0
dataset string, dataset slug
interval optional string, dataset export granularity, one of day, month or quarter, defaults to day
date_from string date in ISO 8601 format, start of date range, e.g. 2016-05-10
date_to string date in ISO 8601 format, end of date range, e.g. 2016-05-20
compressed boolean, when true — generates links to part files, compressed with Gzip; otherwise or if ommitted — generates links to uncompressed part files

Supported dataset slugs:

Slug Description Retention Policy Intervals Supported
app_general_data Apps 30 days day
publisher_general_data Publishers 30 days day
parent_company_general_data Companies 30 days day
sdk_general_data SDKs 30 days day
app_sdks App SDKs 3 months day, month, quarter
app_retention_data Retention Estimates 3 months month
daily_app_estimates App Estimates 3 months day, month, quarter
daily_app_session_data App Sessions 3 months day, month, quarter
daily_app_ratings App Ratings 3 months day, month, quarter
daily_publisher_estimates Daily Publisher Estimates 3 months day, month, quarter
cross_app_usage Cross App Usage 3 months month
app_tags App Tags 3 months day

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

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:

Param Description
itues_connect 'iTunes Connect' store
google_play 'Google Play' store
unified 'iTunes Connect' and 'Google Play' stores combined; should only be used when report does not require a particular store explicitly

Query parameters:

Param Description
report_id string, unique report's identifier
date_from string date in ISO 8601 format, start of date range, e.g. 2020-02-17
date_to string date in ISO 8601 format, end of date range, e.g. 2020-02-17

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

Attribute Description
id integer, parent company id
name string, parent company name
figi string, parent company figi
tickers array of strings, known company tickers
google_play_publisher_ids array of integers, company's Google Play publisher ids
itunes_connect_publisher_ids array of integers, company's iTunes publisher ids

Apps

Attribute Description
name string, app name
description string, app description
category_id integer, primary category id, app store specific
subcategory_id integer, primary subcategory id, if present, app store specific
category_name string, primary category name, app store specific
subcategory_name string, primary subcategory name, app store specific
category_ids list of integer, all app category ids, app store specific
price_cents integer, app price in cents
offers_in_app_purchases boolean, true if app offers IAPs
app_store_url string, url to app store app page
publisher_name string, name of app's publisher
publisher_id integer, id of app's publisher
publisher_url string, optional url to publisher site, provided by publisher
initial_release_date date, date of initial release
current_version string, current version slug
last_update_date date, date of last tracked version update
approx_size_bytes long, approximate size of app in bytes
icon_url string, url for app icon, app store CDN
screenshot_urls array of strings, urls for app screenshots, app store CDN
other_stores optional, array of maps, contains inter-store links, e.g. "other_stores": [{"store": "google_play", "id": "com.king.candycrushsaga"}]
bundle_id iTunes only, returns app's bundle ID defined by Apple
permissions array with app permissions as strings or null, e.g. ["view network connections","full network access"]
apptopia_url string, a URL to an App information page on apptopia.com
privacy_url string, a URL to an App Privacy Policy page, scraped from App Store

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:

Returned attributes:

Attribute Description
id string, app id
country_iso country ISO, iTunes only
versions array of version records, each having version, description and date, e.g.:
  "versions": [
    {
      "version": "1.2.3",
      "description": "bla",
      "date": "2016-01-01"
    },
    ....
  ]

Returned version records are sorted in chronological order.

App Ranks

Param Description
id string, app id
country_iso string, 2 alpha country code according Alpha-2 ISO-3166
date date, day of measurement
kind string, chart name: "free", "paid" or "grossing"
category_id int, category id of chart
rank int, position in rank chart of the given app

App Ranks Summary

Attribute Description
id string, app id
date date, day of measurement
ranks map of form "US": {"6020": {"grossing": 398, "paid": 129}, ...} providing a country -> category -> rank kind -> rank hierarchy

App Estimates

Attribute Description
id string, app id
country_iso string, country code
date date, day for which estimation is made
downloads long, count of downloads
downloads_revenue double, amount of revenue coming from downloads
iap_revenue double, amount of revenue coming from IAPs
total_revenue double, sum of all fractions of revenue
dau long, number of daily active users
mau long, number of monthly active users
arpu double, average revenue per user
engagement double, usage engagement metric

App Sessions

Attribute Description
id string, app id
country_iso string, country code
date date, day for which estimation is made
sessions long, total number of sessions
session_len double, average session length per user in seconds

Publisher Estimates

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

Attribute Description
id string, publisher id
country_iso string, country code
date date, day for which estimation is made
downloads long, count of downloads
downloads_revenue double, amount of revenue coming from downloads
iap_revenue double, amount of revenue coming from IAPs
total_revenue double, sum of all fractions of revenue
dau long, number of daily active users
mau long, number of monthly active users
arpu double, average revenue per user
engagement double, usage engagement metric

App Ratings

Attribute Description
id string, app id
country_iso string, country code
date date, day of measurement
avg_rating double, average rating
ratings_count long, total number of ratings
ratings_breakdown map, breakdown of ratings, e.g: {"1": 0, "2": 0, "3": 1, "4": 100, "5": 300}

iTunes App Store specific attributes:

Attribute Description
current_version_avg_rating double, average rating for current version (on date)
current_version_ratings_count long, number of ratings for current version (on date)
current_version_ratings_breakdown map, breakdown of ratings for current version (on date)

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

Attribute Description
id string, tag id
types map, where keys are app type, i.e. game or non-gameand values a the tag type within the key app type
name string, tag name
category string, tag category
description string, tag description
status string, tag status

SDKs

Attribute Description
id long, sdk id
name string, sdk name
company string, name of SDK company
url string, link to SDK company web site
function string, primary function of SDK
other_stores optional, array of maps, contains inter-store links, e.g. "other_stores": [{"store": "google_play", "id": 123}]

App SDKs

Attribute Description
id string, app id
sdk_id long, sdk id
present boolean, indicates whether sdk referenced by sdk_id is present in app referended by app_id
install_date date, date of tracked installation
uninstall_date date, date of tracked uninstallation
active boolean, indicates whether sdk is active within the app, not just included/linked
activation_date date, date of detection of sdk being active
deactivation_date date, date of detection of sdk being inactive
domains list of strings, known domains sdk is trying to access
uris list of strings, known URIs sdk is trying to access
user_agents list of strings, known User-Agent strings sdk uses

App Tags

General Attributes

Attribute Description
id string, app id
category_id integer, primary category id, app store specific
subcategory_id integer, primary subcategory id, if present, app store specific
category_ids list of integer, all app category ids, app store specific
tags list of Tag records

Tag attributes

Attribute Description
id string, tag id
type string, type of the tag in the context of an app
status string, tag status

SDK Category Performance

Attribute Description
id long, SDK id
date string date
category_performance map with category ids as keys and metrics as keys, e.g.:
    {
      "6014": {"installs": 100},
      "6008": {"installs": 10}
    }

App ads.txt Data

General attributes

Attribute Description
app_id string, app id
status string, one of the success / not_found / error
domain string, discovered domain which hosts app ads file
refreshed_at string, timestamp of the last update
records array of AD domain records

AD domain record attributes

Attribute Description
field_ad_domain string
field_pub_id string
field_type string
field_authority string

Publisher ads.txt Data

Attribute Description
status string, one of the success / not_found / error
domain string, discovered domain which hosts app ads file
refreshed_at string, timestamp of the last update
records array of AD domain records

AD domain record attributes

Attribute Description
field_ad_domain string
field_pub_id string
field_type string
field_authority string

Publishers

General attributes

Param Description
id int, id of publisher
name string, publisher name
profile_url string, url for company LinkedIn profile
website_url string, url for company web site
hq_country string, country of company headquarters
other_stores optional, array of maps, contains inter-store links, e.g. "other_stores": [{"store": "google_play", "id": 456}]
app_ids array of publisher's app IDs
contacts company and employee data imported from Crunchbase, e.g. "contacts": { "company": {...}, "employees": [{...}, ...] }
apptopia_url string, a URL to a Publisher information page on apptopia.com

Contacts attributes

Param Description
company company information
employees array of employee records

Company attributes

Param Description
company_name string, company name
primary_role string, company primary role
short_description string, short company description
categories array of strings, company categories according to Crunchbase
category_groups array of strings, company category groups, according to Crunchbase
status string, company status
address string, company address
city string, company location city
region string, company location region
zipcode string, company location zipcode
state_code string, company location state code
country_code string, company location country code
phone string, phone number
email string, company email
employee_count string, approximate employee count, e.g. "51-100"
founded_on date, company foundation date
closed_on date, company close date
domain string, company domain
logo_url string, company logo URL
profile_image_url string, profile image URL
facebook_url string, company URL in Facebook
twitter_url string, company Twitter URL
linkedin_url string, company LinkedIn URL
homepage_url string, company homepage URL
cb_url string, company URL on Crunchbase

Employee attributes

Param Description
first_name string, employee first name
last_name string, eployee last name
gender string, employee gender
primary_affiliation_organization string, primary company
primary_affiliation_title string, employee title in their primary company
emails array of strings, employee's known emails
logo_url string, employee logo URL
profile_image_url string, employee profile image URL
facebook_url string, employee Facebook page URL
twitter_url string, employee Twitter URL
linkedin_url string, employee LinkedIn URL
cb_url string, emloyee Crunchbase URL
country_code string, country code
state_code string, employee location state code
Attribute Description
name string, name of matched featured list
app_ids array of app ids

Daily rank change

Attribute Description
id string, app id
country_iso string, country code
date date, day for which estimation is made
current_rank integer or null, app rank on the given date
previous_rank integer or null, app rank one day pefore the given date
rank_change integer, amount of rank places an app shifted by. Positive value means rank got higher, negative - rank got lower.
category_id int, category id of chart in which rank change is calculated

New Releases

Same as Apps.

Top Advertisers

General attributes

Param Description
id string, app id
publisher_id integer, id of app's rank
ad_network_sdk_ids list of string, Ad network sdk ids assigned to this app
last_ad_seen string date in ISO 8601 format, last time ad was seen for current app, e.g. 2019-10-18
store identifier, type of App Store (itunes_connect or google_play)
date string date in ISO 8601 format, day of measurement, e.g. 2019-10-18
country_iso list of string, 2 alpha country code according Alpha-2 ISO-3166

Top Publishers

General attributes

Param Description
id string, app id
rank integer, advertising app rank
publisher_id integer, id of app's publisher
ad_network_sdk_ids list of string, Ad network sdk ids assigned to this app
store identifier, type of App Store (itunes_connect or google_play)
date string date in ISO 8601 format, day of measurement, e.g. 2019-10-18
country_iso list of string, 2 alpha country code according Alpha-2 ISO-3166

Search Endpoints

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

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:

Predicate Description
match fuzzy string match
= equality check
in inclusion in a list of values check
> greater than check
>= greater than or equal to check
< less than check
<= less than or equal to check

Applicable predicates based on attribute type:

Type Predicate
string match
identifier =, in
integer =, in, >, >=, <, <=
float =, in, >, >=, <, <=
date =, in, >, >=, <, <=

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

Attribute Description
store_type identifier, type of App Store (itunes_connect or google_play)
ref_no identifier, App ID within its App Store
name string, App name
primary_category_id integer, primary App's category ID
primary_subcategory_id integer, primary App's subcategory ID
category_ids list of integer, a list of app App's category IDs
kind identifier, free or paid
publisher_id integer, App's publisher ID
sdk_ids list of integers, a list of known SDK IDs used in App
sdk_count integer, amount of SDKs installed
dls_tier_30d float, approximate downloads within last 30 days, as of the moment of request
rev_tier_30d float, approximate revenue within last 30 days, as of the moment of request
dau float, approximate number of daily active users, as of the moment of request
mau float, approximate number of monthly active users, as of the moment of request
tags list of identifiers, a list of all App tags set by Apptopia
released_on date, release date
last_version_update_on date, last version update date

Publisher attributes which can be used in search filters:

Attribute Description
store_type identifier, type of App Store (itunes_connect or google_play)
ref_no identifier, Publisher ID
name string, Publisher name
total_apps_count integer, total amount of known Publisher's apps
app_ids list of identifiers, all known Publisher's App ids
dls_tier_30d float, approximate downloads within last 30 days, as of the moment of request
rev_tier_30d float, approximate revenue within last 30 days, as of the moment of request
tags list of identifiers, a list of all App tags set by Apptopia

Parent company attributes which can be used in search filters:

Attribute Description
parent_company_id identifier, Company ID
parent_company_name string, Company name
parent_company_figi string, Financial Instrument Global Identifier
parent_company_ticker string, used to uniquely identify publicly traded shares of a particular stock

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:

Param Description
id optional, number, unique query's identifier (to simplify distinction in case of multi-request)
name string, represent name of wanted publisher
domain string, publishers domain
email_domain string, publishers email domain
hq_country_iso2 string, publisher's HQ country code in ISO 3166-1 alpha-2 format, e.g. 'US'
founded_on string, date of foundation in ISO 8601 format, e.g. '2021-01-11'
twitter_url string, URL of publisher's Twitter page
facebook_url string, URL of publisher's Facebook page
linkedin_url string, URL of publisher's LinkedIn page
crunchbase_url string, URL of publisher's Crunchbase page

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

The result records attributes are

Attribute Description
score matching score, based on matched query attributes, the higher - the better
matched_attributes json object of matched attributes
publisher_data json object, represent publisher data (id, store, contacts, set of app ids, etc.) that corresponds to the matched_attributes

FAQ

What time frames can I pull with the API?

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.

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