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 by name
Section titled “Match by name”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 by attributes
Section titled “Filter by attributes”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]]]]Combine matching and filters
Section titled “Combine matching and filters”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:
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]]]]'Read the response
Section titled “Read the response”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.
Match structured fields
Section titled “Match structured fields”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.
Filter predicates
Section titled “Filter predicates”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, >, >=, <, <= |
App filter attributes
Section titled “App filter attributes”| 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 filter attributes
Section titled “Publisher filter attributes”| 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 filter attributes
Section titled “Parent company filter attributes”| 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 |