Skip to content

Search

Search apps, publishers, and parent companies with these three endpoints:

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

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

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

Single string match example form:

["match", "instagram"]

Match example form with multiple strings:

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

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

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

filters are combined via logical AND.

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

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

instead of:

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

However both forms are valid.

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

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

This query finds names matching “kingdom” or “batman”, excludes primary category 6014, and requires approximate revenue above 100 and downloads above 1,000 in the last 30 days:

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

Terminal window
curl -X "POST" "https://integrations.apptopia.com/api/app_search?limit=5" \
-H "Authorization: $APPTOPIA_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]]]]'

App search returns an app_ids object containing arrays of IDs grouped by store. Publisher search uses the same store grouping under publisher_ids. Apple App Store app IDs and publisher IDs are integers; Google Play app IDs are package-name strings.

For example, an abbreviated app-search response is:

// Abbreviated response; omitted fields and records are shown as ...
{"app_ids":
{
"google_play":[
"com.gameloft.android.ANMP.GloftDYHM","com.turner.cardwars2", ...],
"itunes_connect":[
438404619,1154895849,1117002117, ...]
}
}

Parent-company search returns a flat company_ids array, without store grouping:

{ "company_ids": [1234567890] }

This ID is illustrative. Empty searches return empty ID collections.

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

To search publishers by store URL, send the following body to /api/publisher_search:

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

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, >, >=, <, <=
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
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
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