NAV Navbar
  • Apptopia Data API
  • Overview
  • Data Matrix
  • Authentication
  • Limits
  • Conventions on IDs
  • API Endpoints
  • Attributes
  • Apptopia Data API

    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

    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.

    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"
    

    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/: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/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/:store/app_graph app graph data
    /api/:store/app_graph/discovery discovery endpoint for app graph data
    /api/:store/pub_graph publisher graph data
    /api/:store/pub_graph/discovery discovery endpoint for publisher 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

    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:

    Chinese Stores

    Chinese app stores xiaomi, mobile_360 and tencent have datasets aimed at apps and app SDKs. API Endpoints that provide data for those stores are:

    Endpoint Description
    /api/:store/categories list of categories
    /api/:store/app app metadata
    /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_sdks/discovery discovery endpoint for app SDKs data
    /api/:store/ratings per app ratings history
    /api/:store/ratings/discovery discovery endpoint for app ratings data

    Directory Endpoints

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

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

    Discovery Endpoints

    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:

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

    Time Series Endpoints

    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

    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",
          "ad_revenue": 0.0
        },
        ...
        {
          "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",
          "ad_revenue": 0.0
        },
        ...
      ]
    

    Time Series Discovery Endpoints

    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.

    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": ....}
    

    Entity Lookup Endpoints

    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.

    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
        }
      ]
    

    Store Top Charts

    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"

    Consider 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,
            ...
          ]
        }
      ]
    

    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).

    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
        ]
      }
    ]
    

    App daily rank change

    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

    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
      }
    ]
    

    App New releases

    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

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

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

    App Graph

    Endpoint that provides app graph connections between apps with weight: /api/:store/app_graph Query parameters: - id[] or ids with one or more app identifiers - date - date in ISO 8601 format for which to find app graph data

    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 Graph /api/:store/app_graph/discovery takes the same partition parameters as other discovery endpoints.

    Publisher Graph

    Endpoint that provides publisher graph connections between publishers: /api/:store/pub_graph Query parameters: - id[] or ids with one or more publisher identifiers - date - date in ISO 8601 format for which to find publisher graph data

    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 Publisher Graph /api/:store/pub_graph/discovery takes the same partition parameters as other discovery endpoints.

    App Retention

    Endpoint that provides app retention data: /api/:store/app_retention Query parameters: - id[] or ids with one or more app identifiers - 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.

    Category Retention

    Endpoint that provides category retention data: /api/:store/category_retention Query parameters: - id[] or ids with one or more category identifiers - 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

    Endpoint that provides app demographics data: /api/:store/app_demographics Query parameters: - id[] or ids with one or more app identifiers - 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.

    Top Advertisers

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

    [
      {
        "id": "com.contextlogic.wish",
        "name": "Wish",
    
        // Rank is calculated the same way as on apptopia.com.
        // Advertisers should be ordered by impressions_share DESC
        // their position in the ordered link is their rank.
        "rank": 1,
    
        // AD networks an advertiser was advertising in on [date_from, date_to]
        "ad_networks": ["AdColony", "AdMob", ...],
    
        // Countries an advertiser was advertising in on [date_from, date_to]
        "countries": ["US", "CA", "RU", ...],
    
        // Impressions share on [date_from, date_to] per AD network
        "impressions_share": {
          "AdMob": 0.026,
          ...
        },
    
        // All creatives an advertiser was displaying on [date_from, date_to]
        "creatives": [
          {
            "ad_network": "AdMob",
    
            // A list of know media files for the impression, up to 100
            "media_urls": [
              "https://s3.amazonaws.com/tom-media-admob-production/c8a7/b8cc/efcfc203f153a9ac4ca29e2104d9c267.png",
              ...
            ],
    
            "ad_type": "Banner",
    
            // Impressions share within Advertiser on [date_from, date_to]
            "impressions_share": 0.132,
    
            "last_seen": "2017-12-06",
            "total_runtime_days": 19,
          },
          ...
        ]
      },
      ...
    ]
    

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

    Query parameters:

    Param Description
    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

    Top Ad Publishers

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

    [
      {
        "id": 1009442510,
        "name": "Colorfy: Coloring Book & Games",
        // Countries a publisher was advertising in on [date_from, date_to]
        "countries": ["US", "CA", "RU", "AU",...],
    
        // AD networks a publisher advertised advertisers on [date_from, date_to]
        "ad_networks": ["adcolony", "applovin", "vungle"],
    
        // List of apps which were advertised by publisher on [date_from, date_to]
        "advertisers": [
          {
            "name": "Pandora Music",
            "id": 284035177
          },
          {
            "name": "Facebook",
            "id": 284882215
          },
          {
            "name": "Stitcher for Podcasts",
            "id": 288087905
          },
          ...
        ],
        // AD network types a publisher advertised apps in [date_from, date_to]
        "ad_types": ["video"],
    
        // All creatives an publisher displayed on [date_from, date_to]
        "creatives": [
          {
            "ad_network": "vungle",
            // A list of know media files for the impression, up to 100
            "media_urls": [
              "https://s3.amazonaws.com/tom-media-vungle-production/dfd3/2dda/4ed732915794f85c410ea8199cbade53.mp4"
            ],
            "ad_type": "video",
            "last_seen_at": "2018-07-02",
            "total_runtime_days": 104,
            // Impressions share within Publisher on [date_from, date_to]
            "impressions_share": 0.134562
          },
        ....
      },
      ...
    ]
    

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

    Query parameters:

    Param Description
    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

    Bulk Data Exports

    This endpoint gives access to daily dumps of:

    Endpoint path: /api/:store/data_dumps

    Query parameters:

    Param Description
    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
    app_general_data Apps
    publisher_general_data Publishers
    sdk_general_data SDKs
    app_sdks App SDKs
    daily_app_estimates App Estimates
    daily_app_session_data App Sessions
    daily_publisher_estimates Daily Publisher Estimates

    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.

    Attributes

    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

    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
    ad_revenue double, amount of revenue coming from ads monetization
    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
    breakout map of form {"6014": {"paid": 0.901}}, here 2 levels of keys are category ids and rank kinds, values represent breakout probability

    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
    ad_revenue double, amount of revenue coming from ads monetization
    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".

    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

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

    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
    name string, app name
    rank integer, advertising app rank
    ad_networks list of string, ad network names, e.g. AdColony, AdMob
    countries list of string, 2 alpha country code according Alpha-2 ISO-3166
    impressions_share float, share of impressions an advertising app had on [date_from, date_to] in selected AD network
    creatives list of creative records, list of creatives seen for an advertising app had on [date_from, date_to] date range

    Creative attributes

    Param Description
    ad_network string, ad network name
    media_urls list of string, urls of creative media files
    ad_type string, ad type name, e.g. Banner
    impressions_share float, share of impressions a creative had on [date_from, date_to] within an an advertising app
    last_seen string, 2 alpha country code according Alpha-2 ISO-3166, last time a creative was seen by the system
    total_runtime_days integer, amount of days a creative was seen by the system

    Top Pubishers

    General attributes

    Param Description
    id string, app id
    name string, app name
    ad_networks list of string, ad network names, e.g. adcolony
    ad_types list of string, ad network types, e.g. video
    countries list of string, 2 alpha country code according Alpha-2 ISO-3166
    impressions_share float, share of impressions an publisher app had on [date_from, date_to] in selected AD network
    creatives list of creative records, list of creatives seen within publisher app on [date_from, date_to] date range

    Creative attributes

    Param Description
    ad_network string, ad network name
    media_urls list of string, urls of creative media files
    ad_type string, ad type name, e.g. Banner
    impressions_share float, share of impressions a creative had on [date_from, date_to] within an an advertising app
    last_seen_at string, 2 alpha country code according Alpha-2 ISO-3166, last time a creative was seen by the system
    total_runtime_days integer, amount of days a creative was seen by the system

    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, ...]
        }
      }
    

    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