NAV
shell

SearchMan’s App Store API

# API Endpoint
http://api.searchman.io/v1/

SearchMan’s App Store API is designed so that you can query the iOS App Store and Google Play in any way you want. You can fetch category rankings for all categories, search rankings for any keyword and find app metadata for all apps in the store.

SearchMan’s App Store API is organized around REST. JSON will be returned in all responses from the API, including errors (though if you use API bindings, we will convert the response to the appropriate language-specific object).

Authentication

# Sample Request

curl "http://api.searchman.io/v1/ios/us/category/list?apiKey=YOUR_API_KEY"

You authenticate to the SearchMan API by providing one of your API keys as a GET parameter in the request. Your API keys carry many privileges, so be sure to keep them secret!

API Credits

Each API request consumes “credits”. You can see how many credits each API requires here. Most of our API requires 1 credit per API request, unless specified in this document below.

Request & Response

# Response includes 'status', 'response_msec' and 'data':
{
 "status": 200,
 "response_msec": "123",
 "data": {

  }
}
# If 'status' is not 200 (i.e. error), API also provides 'msg':
{
 "status": 404,
 "response_msec": "123",
 "msg": "not found"
}

API request requires $platform and $country in the url:

http://api.searchman.io/v1/$platform/$country/xyz

Parameters

Parameter Default
$platform Either ios for Apple App Store or android for Google Play.
$country ISO 3166-1 alpha-2 country code.

There are other common parameters:

Parameter Default
$device iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).
$categoryId Each store’s category id, which you can get by quering Cateogory List API.
$selection Type of category ranking. free, paid or grossing.
$appId The indenfier of each app in the store. 9 digit integer for ios and bundle id for android.

Available Countries

Most APIs are available only for us (USA) and jp (Japan).

Following APIs accept any $country listed in the table below.

List of Available Countries

Country $country
United States us
Japan jp
United Kingdom gb
Canada ca
Brazil br
China cn
Russia ru
India in
South Korea kr
Mexico mx
Taiwan tw
Germany de
France fr
Australia au
Indonesia id
Turkey tr
Thailand th
Colombia co
Argentina ar

App Object

# Example of <appObjectDetail> for Facebook Messanger for Google Play in the US.
{
  "appId":"com.facebook.orca",
  "appName":"Facebook Messenger",
  "primaryCategoryId":"COMMUNICATION",
  "iconUrl":"https:\/\/lh5.ggpht.com\/0VYAvZLR9YhosF-thqm8xl8EWsCfrEY_uk2og2f59K8IOx5TfPsXjFVwxaHVnUbuEjc=w100",
  "price":0,
  "currency":"USD",
  "formattedPrice":"Free",
  "releaseDate":"Oct 9, 2014",
  "version":"13.0.0.19.13",
  "studioId":"Facebook",
  "studioName":"Facebook",
  "studioUrl":"http:\/\/www.facebook.com\/apps\/application.php?id=256002347743983",
  "userRatingCount":10148561,
  "commentCount":2119673,
  "averageUserRating":3.8996832370758,
  "starRatings":{
    "1":1563269,
    "2":446497,
    "3":934393,
    "4":1705205,
    "5":5499132
  },
  "numDownloads":"500,000,000+",
  "categoryIds":[
    "COMMUNICATION"
  ],
  "description":"Instantly reach the people in your ...",
  "releaseNotes":"Thanks for using Messenger! ....",
  "permissions": [
    "com.android.vending.BILLING",
    "android.permission.INTERNET",
    "android.permission.ACCESS_NETWORK_STATE",
    "android.permission.ACCESS_WIFI_STATE",
    "android.permission.WAKE_LOCK",
    "android.permission.READ_PHONE_STATE",
    "android.permission.BLUETOOTH",
    "android.permission.BLUETOOTH_ADMIN",
    "android.permission.ADD_SYSTEM_SERVICE",
    "android.permission.WRITE_CALENDAR",
    "android.permission.GET_ACCOUNTS",
    "com.google.android.c2dm.permission.RECEIVE",
    "com.pandora.android.permission.C2D_MESSAGE",
    "android.permission.WRITE_EXTERNAL_STORAGE",
    "android.permission.READ_EXTERNAL_STORAGE",
    "android.permission.RECEIVE_BOOT_COMPLETED",
    "com.android.launcher.permission.INSTALL_SHORTCUT"
  ],
  "screenshotUrls":[
    "https:\/\/lh6.ggpht.com\/PayBkmABpA_UEtJuO21O9DaYlZrO4_XbWpRuMlGD5JMJuOw4h5QD0gJ_NWXOnBqZgQ",
    "https:\/\/lh5.ggpht.com\/S3udjKLR0045VRTGmKSCRq6n_-JVM084xH36SYUmjRnc8zZ2Gcq8eL7bixe-cscP_A",
    "https:\/\/lh4.ggpht.com\/Idi8NCyRZHGQ8V1h64dGqD-N7PGym27FghdYtRqCY1H5HP5wRZwjISS8RB2XXnwh6Q",
    "https:\/\/lh6.ggpht.com\/reXX4Sm0tmG5vu534eddDzgBW8R3s3ysmVCpMuXphHSDXct92G8vRpJQis7ZgCHe0Q",
    "https:\/\/lh5.ggpht.com\/2FjQK1nkRoihPnafEG3KxuO5UkRDjZKfHUPcZgtz1jgB-zpKg9tduPEuX2jjK23WpwKv",
    "https:\/\/lh5.ggpht.com\/dH_Znb__NjJkyQ0_HW4TPniO3pnfXqhVF9xQ2r06bj_z0PGXIKIIxw0GlvDmKWYUDw",
    "https:\/\/lh6.ggpht.com\/qvqDEwA-q0qKrXMfMTaI6GYymqI1sdmS00QYoEYNn_fR2Eh2hIsHKs-D_9c1q9EV5m7N"
  ],
  "similarAppIds":[
    "com.whatsapp",
    "com.facebook.katana",
    "com.asapchat.android",
    "com.skype.raider",
    "jp.naver.line.android",
    "com.viber.voip",
    "com.yahoo.mobile.client.android.im",
    "com.spartancoders.gtok",
    "com.bsb.hike",
    "com.tencent.mm",
    "com.instagram.android",
    "com.google.android.talk",
    "com.bbm",
    "com.android.chrome",
    "org.telegram.messenger",
    "com.opera.mini.android",
    "com.jb.gosms",
    "org.mozilla.firefox",
    "com.contapps.android.messaging",
    "com.antivirus"],
  "alsoInstalledAppIds":[
    "com.sandesh.whoisonline",
    "com.xtended.letstalk",
    "lovemessanger.third.madfox",
    "com.socialize.greentwitt",
    "com.tinkle.android.main",
    "com.sitoplex.addfriends",
    "com.zixstudio.birthdayschedulerforfb",
    "com.spartancoders.gtok",
    "com.mjr.pink",
    "com.socialstatus.socialstatus",
    "com.dogwatchmedia",
    "com.meeble.talkdroidpro",
    "com.ruknaa.sharekamkom",
    "flashbang.apps.fbtrack",
    "com.gmm.atimemedia",
    "com.socialize.greenwhite",
    "com.yahoo.mobile.client.android.imvideo",
    "com.dd.fb_camera_paid",
    "com.FacebookLeaversApp",
    "com.hyxen.app.GeoMe"
  ]
}

2 types of app objects

We provide 2 patterns of appObject based on the need. appObjectDetail contains all metadata for the app, while appObject contains less data.

App Metadata API uses appObjectDetail so that you can use all details of the app. All other APIs use appObject to reduce the amount of data.

Common Elements in appObject & appObjectDetail

Parameter Description
appId Identifier of the app.
appName Name of the app.
primaryCategoryId Primary category id of the app.
iconUrl Url of the icon. Usually 100x100 pixel.
price Price of the app.
currency Currency of the price.
formattedPrice Formatted price using currency & price.
version Version of the latest version.
fileSizeBytes File size of the app by byte. Currently ios only.
releaseDate For ios, initial release date of the app. For android, latest version update.
studioId Identifier of the studio of the app.
studioName Name of the studio of the app.
studioUrl Url of the studio of the app.
hasInAppPurchases 1 if the app offers in-app-purchases.
userRatingCount Number of ratings of the app.
commentCount Number of reviews of the app. Currently android only.
averageUserRating Average stars (1 to 5) of the app.
starRatings Array. Breakdown of ratings by star.

Elements only in appObjectDetail

Parameter Description
bundleId bundleId of the app. ios only.
numDownloads Number of downloads of the app. Currently android only.
categoryIds Array. Category ids of the app.
description Description of the app.
releaseNotes Release notes of the latest version.
permissions Permissions each app requires. Currently android only.
screenshotUrls Array. Urls of the screenshots.
ipadScreenshotUrls Array. Urls of the screenshots. Currently iPad compatible apps only.
videoUrl Url of the video. Currently android only.
videoScreenUrl Url of the video screen. Currently android only.
userRatingCountCurrent Number of ratings of the current version. Currently ios only.
averageUserRatingCurrent Average stars (1 to 5) of the current version. Currently ios only.
starRatingsCurrent Array. Breakdown of ratings by star for the current version. Currently ios only.
similarAppIds Array. List of the appIds of the similar apps. Currently android only.
alsoInstalledAppIds Array. List of the appIds of “User Also Installed”.

Keyword Object

# Example of <keywordObject> of a keyword "dating apps" for Google Play in the US.
{
  "keyword": "dating apps",
  "inAutocomplete": 1,
  "hits": 2159,
  "traffic": 82,
  "hasRelated": 1
}

Elements in keywordObject

Parameter Description
keyword keyword
inAutocomplete Whether the keyword appears in “autucomplete” (1=true, 0=false). A keyword in “autocompete” typically has a very high traffic.
traffic Estimated search traffic/volume of the keyword (0 to 100) in App Store or Google Play Store.
hits Number of hits for the keyword. (For Google Play, maximum hits is 250.)
hasRelated Whether the keyword has “Related Keywords” or not (1=true, 0=false). A keyword which has “Related Keywords” typically has a very high traffic. Currently available for ios & us only.

API Details

Category List API

# To retrive list of categories for Google Play Store in the US.

curl "http://api.searchman.io/v1/android/us/category/list?apiKey=YOUR_API_KEY"
{
  "data": {
    "BOOKS_AND_REFERENCE": {
      "categoryId": "BOOKS_AND_REFERENCE",
      "categoryName": "Books & Reference"
    },
    "BUSINESS": {
      "categoryId": "BUSINESS",
      "categoryName": "Business"
    },
    "GAME_PUZZLE": {
      "categoryId": "GAME_PUZZLE",
      "categoryName": "Games - Puzzle",
      "parentCategoryId": "GAME"
    }
  }
}

This endpoint retrieves all categories in the store.

Definition

GET /v1/$platform/$country/category/list

Query Parameters

N/A

Response Format

$json['data'][$categoryId] = $categoryObject

$json['data'][$categoryId]['categoryId'] = $categoryId

$json['data'][$categoryId]['categoryName'] = $categoryName

Category Ranking API

# To retrive Top Grossing apps in "All Apps" categories for Google Play Store in the US.

curl "http://api.searchman.io/v1/android/us/category/rank?categoryId=all&selection=grossing&apiKey=YOUR_API_KEY"
{
  "data": {
    "1": "<appObject>",
    "2": "<appObject>",
    "3": "<appObject>",
    "4": "<appObject>"
  }
}

This endpoint retrieves top apps in each category and selection in the store.

Definition

GET /v1/$platform/$country/category/rank

Query Parameters

Parameter Required Description
categoryId Y Category Id, which you get from Category List API.
selection Y Type of category ranking. free, top or grossing.
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).
start N A cursor for use in pagination. default = 1.
count N A limit on the number of objects to be returned. Limit can range between 1 and 25 items. default = 25.

Response Format

$json['data'][$rank] = $appObject

Category Ranking API (ID Only)

# To retrive Top apps in "All Apps" categories for Google Play Store in the US.

curl "http://api.searchman.io/v1/android/us/category/rank/ids?categoryId=all&apiKey=YOUR_API_KEY"
{
  "data": {
    "android": {
      "free": {
        "1": "com.facebook.orca",
        "2": "com.facebook.katana",
        "3": "com.pandora.android",
        "4": "com.instagram.android"
      }
    }
  }
}

This endpoint retrieves top apps' appIds in each category in the store.

Definition

GET /v1/$platform/$country/category/rank/ids

Credits per API request

5 credits per API request

Query Parameters

Parameter Required Description
categoryId Y Category Id, which you get from Category List API.

Response Format

$json['data'][$device][$selection][$rank] = $appId

# To retrive historical category ranking in "All Apps" categories for Google Play Store in the US.

curl "http://api.searchman.io/v1/android/us/category/trend?categoryId=all&apiKey=YOUR_API_KEY"
{
  "data": {
    "com.facebook.katana": {
      "android": {
        "free" : {
          "2014-03-04" : 1,
          "2014-03-05" : 1,
          "2014-03-06" : 2,
          "2014-03-07" : 1,
          "2014-03-08" : 1,
          "2014-03-09" : 1
        }
      }
    }
  }
}

This endpoint retrieves historical category ranking in each category in the store.

Definition

GET /v1/$platform/$country/category/trend

Credits per API request

10 credits per API request

Query Parameters

Parameter Required Description
categoryId Y Category Id, which you get from Category List API.

Response Format

$json['data'][$appId][$device][$selection][$date] = $rank

Category Ranking by Apps API

# To retrive historical category ranking of Facebook and Twitter from 2016-02-14 to 2016-02-15 for Google Play Store in the US.

curl "http://api.searchman.io/v1/android/us/category/trend/byAppIds?appIds=com.facebook.katana,com.twitter.android&startDate=2016-02-14&endDate=2016-02-15&apiKey=YOUR_API_KEY"
{
  "data": {
    "trends": {
      "com.facebook.katana": {
        "2016-02-14": {
          "android": {
            "SOCIAL": {
              "free" : 1
            },
            "SOCIAL": {
              "APPLICATION" : 2
            }
          }
        },
        "2016-02-15": {
          "android": {
            "SOCIAL": {
              "free" : 1
            },
            "SOCIAL": {
              "APPLICATION" : 2
            }
          }
        }
      }
    },
    "dates":[
      "2016-02-14",
      "2016-02-15"
    ],
    "categories": [
      {
        "device": "android",
        "categoryId": "SOCIAL",
        "selection": "free",
        "deviceName": "Google Play",
        "categoryName": "Social",
        "selectionName": "Top Free"
      },
      {
        "device": "android",
        "categoryId": "APPLICATION",
        "selection": "free",
        "deviceName": "Google Play",
        "categoryName": "All Applications",
        "selectionName": "Top Free"
      }
    ]
  }
}

This endpoint retrieves historical category ranking for specific apps in the store.

Definition

GET /v1/$platform/$country/category/trend/byAppIds

Credits per API request

10 credits per day per AppId

(eg. Requesting category rankings for 5 days for 2 apps will use 100 credits.)

Query Parameters

Parameter Required Description
appIds Y List of AppIds. Comma-separated. Up to 5 apps.
startDate Y Start date (YYYY-mm-dd)
endDate Y End date (YYYY-mm-dd). endDate - startDate has to be 31 days or less.

Response Format

$json['data']['trends'][$appId][$date][$device][$selection][$date] = $rank

$json['data']['dates'][] = $date

$json['data']['categories'][] = $category

Search API

# To retrive top apps when user searches by "photo" in Google Play Store in the US.

curl "http://api.searchman.io/v1/android/us/search/rank?q=photo&apiKey=YOUR_API_KEY"
{
  "data": {
    "1": "<appObject>",
    "2": "<appObject>",
    "3": "<appObject>",
    "4": "<appObject>"
  }
}

This endpoint retrieves search results for any query.

Definition

GET /v1/$platform/$country/search/rank

Query Parameters

Parameter Required Description
q Y Query. urlencode is required.
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).
start N A cursor for use in pagination. default = 1.
count N A limit on the number of objects to be returned. Limit can range between 1 and 25 items. default = 25.

Response Format

$json['data'][$rank] = $appObject

Search API (ID Only)

# To retrive top apps when user searches by "photo" in Google Play Store in the US.

curl "http://api.searchman.io/v1/android/us/search/rank/ids?q=photo&apiKey=YOUR_API_KEY"
{
  "data": {
    "1": "com.pixlr.express",
    "2": "com.zentertain.photoeditor",
    "3": "com.zentertain.photocollage",
    "4": "com.roidapp.photogrid"
  }
}

This endpoint retrieves top apps' appIds for any query.

Definition

GET /v1/$platform/$country/search/rank/ids

Credits per API request

5 credits per API request

Query Parameters

Parameter Required Description
q Y Query. urlencode is required.
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).

Response Format

$json['data'][$rank] = $appId

# To retrive historical category ranking under "photo" in Google Play Store in the US.

curl "http://api.searchman.io/v1/android/us/search/trend?q=photo&apiKey=YOUR_API_KEY"
{
  "data": {
    "com.facebook.katana": {
      "android": {
        "2014-03-04" : 1,
        "2014-03-05" : 1,
        "2014-03-06" : 2,
        "2014-03-07" : 1,
        "2014-03-08" : 1,
        "2014-03-09" : 1
      }
    }
  }
}

This endpoint retrieves historical search ranking for each query.

Definition

GET /v1/$platform/$country/search/trend

Credits per API request

10 credits per API request

Query Parameters

Parameter Required Description
q Y Query. urlencode is required.

Response Format

$json['data'][$appId][$device][$date] = $rank

# To retrive trending keywords (trending searches) in App Store (iPhone) in the US.

curl "http://api.searchman.io/v1/ios/us/keyword/trends?device=iPhone&apiKey=YOUR_API_KEY"
{
  "data": {
    "trendingKeywords": {
      "1450008000": [
        "jelly blast",
        "toy army",
        "yfdownloader",
        "loop ball",
        "photo math",
        "soma",
        "adventure time",
        "project color™ by the home depot",
        "fox sports go",
        "uber"
       ]
     }
  }
}

This endpoint retrieves trending keywords (trending searches) in iOS App Store.

Definition

GET /v1/$platform/$country/keyword/trends

Credits per API request

1 credit per day (eg. Requesting trending keywords for 3 days will use 3 credits.)

Query Parameters

Parameter Required Description
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).
start N Timestamp of start time (Unix epoch).
end N Timestamp of end time (Unix epoch). end - start has to be 7 days or less.

If both start and end are not provided, this API will return trending keywords at that moment.

Response Format

$json['data']['trendingKeywords'][$epochUTC][] = $keyword

# To retrive trending keywords (trending searches) with keyword stats in App Store (iPhone) in the US.

curl "http://api.searchman.io/v1/ios/us/keyword/trends/stats?device=iPhone&apiKey=YOUR_API_KEY"
{
  "data": {
    "trendingKeywords": {
      "1450008000": [
        {
          "keyword": "free games",
          "inAutocomplete": 1,
          "hits": 2165,
          "traffic": 99,
          "hasRelated": 1
        },
        {
          "keyword": "shade spotter",
          "inAutocomplete": 1,
          "hits": 147,
          "traffic": 76,
          "hasRelated": 0
        }
       ]
     }
  }
}

This endpoint retrieves trending keywords (trending searches) with keyword stats in iOS App Store.

Definition

GET /v1/$platform/$country/keyword/trends/stats

Credits per API request

10 credits per day (eg. Requesting trending keywords for 3 days will use 30 credits.)

Query Parameters

Parameter Required Description
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).
start N Timestamp of start time (Unix epoch).
end N Timestamp of end time (Unix epoch). end - start has to be 7 days or less.

If both start and end are not provided, this API will return trending keywords at that moment.

Response Format

$json['data']['trendingKeywords'][$epochUTC][] = $keywordObject

Autocomplete API

# To retrive suggested keywords when a user types "photo" in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/keyword/hints?q=photo&apiKey=YOUR_API_KEY"
{
  "data": [
    "photofunia",
    "photo editor cut and paste",
    "photo editing software without internet",
    "photo grid frames",
    "photo collage and editor at the same time"
  ]
}

This endpoint retrieves suggested keywords by autocomplete in each device.

Definition

GET /v1/$platform/$country/keyword/hints

Query Parameters

Parameter Required Description
q Y Query. urlencode is required.
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).

Response Format

$json['data'][] = $keyword

Autocomplete + Stats API

# To retrive suggested keywords with stats when a user types "dating" and "photo" in App Store in the US.

curl "http://api.searchman.io/v1/ios/us/keyword/hints/stats?keywords=%5B%22dating%22%2C%22photo%22%5D&apiKey=YOUR_API_KEY"
{
  "data": {
    "keywords": {
      "dating": [
        {
          "keyword": "dating apps",
          "inAutocomplete": 1,
          "hits": 2159,
          "traffic": 82,
          "hasRelated": 1
        },
        {
          "keyword": "dating",
          "inAutocomplete": 1,
          "hits": 2162,
          "traffic": 79,
          "hasRelated": 1
        }
       ]
     }
  }
}

This endpoint retrieves suggested keywords with stats by autocomplete in each device.

Definition

GET /v1/$platform/$country/keyword/hints/stats

Credits per API request

10 credits per input query

Query Parameters

Parameter Required Description
keywords Y Up to 5 queries. Json-encoded. urlencode is required.
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).

Response Format

$json['data']['keywords'][$query][] = $keywordObject

# To retrive related keywords given a root keyword "dating" in iPhone in the US.

curl "http://api.searchman.io/v1/ios/us/keyword/related?q=dating&apiKey=YOUR_API_KEY"
{
  "data": [
    "chat",
    "online chat",
    "personals",
    "dating chat",
    "social chat",
    "singles chat"
  ]
}

This endpoint retrieves related keywords given a root keyword.

Definition

GET /v1/$platform/$country/keyword/related

Query Parameters

Parameter Required Description
q Y Query. urlencode is required.
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).

Response Format

$json['data'][] = $keyword

# To retrive related keywords with stats given root keywords of "dating" and "photo" in iPhone in the US.

curl "http://api.searchman.io/v1/ios/us/keyword/related/stats?keywords=%5B%22dating%22%2C%22photo%22%5D&apiKey=YOUR_API_KEY"
{
  "data": {
    "keywords": {
      "dating": [
        {
          "keyword": "personals",
          "inAutocomplete": 1,
          "hits": 1031,
          "traffic": 68,
          "hasRelated": 1
        },
        {
          "keyword": "singles",
          "inAutocomplete": 1,
          "hits": 2126,
          "traffic": 83,
          "hasRelated": 1
        }
       ]
     }
  }
}

This endpoint retrieves related keywords with stats given root keywords.

Definition

GET /v1/$platform/$country/keyword/related/stats

Credits per API request

10 credits per input query

Query Parameters

Parameter Required Description
keywords Y Up to 5 queries. Json-encoded. urlencode is required.
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).

Response Format

$json['data']['keywords'][$query][] = $keywordObject

App Metadata API

# To retrive detailed app metadata for Facebook Messanger and Pandora in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/apps?appIds=com.facebook.orca,com.pandora.android&apiKey=YOUR_API_KEY"
{
  "data": {
    "com.facebook.orca" : "<appObjectDetail>",
    "com.pandora.android" : "<appObjectDetail>"
  }
}

This endpoint retrieves detailed app metadata for multiple apps in a request.

Definition

GET (or POST) /v1/$platform/$country/apps

Credits per API request (without “Realtime Fetch”)

1 to 20 credits per API request, depending on the number of appIds in the request.

Required credits = ceil [ count(appIds) / 5 ]

Credits per API request (with “Realtime Fetch”)

10 credits per each appId in appIds in the request.

Required credits = count(appIds) * 10

Query Parameters

Parameter Required Description
appIds Y List of AppIds. Comma-separated. Up to 100 apps (without “Realtime Fetch”), up to 5 apps (with “Realtime Fetch”).
realtimeFetch N Set 1 to fetch apps' metadata at real time. Default = 0.

Response Format

$json['data'][$appId] = $appObjectDetail

App Registration API

# To register Pandora in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/app/register?appId=com.pandora.android&apiKey=YOUR_API_KEY"
{
  "data": {
    "com.pandora.android" : "<appObject>"
  }
}

Given an App ID missing in the datastore, this endpoints adds that app into the API and returns metadata for that app.

Definition

POST (or GET) /v1/$platform/$country/app/register

Query Parameters

Parameter Required Description
appId Y AppId.

Response Format

$json['data'][$appId] = $appObject

App Keywords API

# To retrive keywords for Instagram in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/app/keywords?appId=com.instagram.android&apiKey=YOUR_API_KEY"
{
  "data": {
    "android":{
      "photo":8,
      "blur":118,
      "twitter":2,
      "feed":6,
      "facebook":4,
      "click":204,
      "depth":51,
      "follower":40,
      "instagram":1,
      "post":7,
      "radial":11,
      "moment":103,
      "people":63,
      "comment":39,
      "user":142,
      "linear":142,
      "flickr":247,
      "interact":48,
      "tumblr":5,
      "foursquare":4
    }
  }
}

This endpoint retrieves keywords which the app a) contains in publicly available information (appName or description) and b) is ranked for under the top 250.

Definition

GET /v1/$platform/$country/app/keywords

Query Parameters

Parameter Required Description
appId Y AppId.

Response Format

$json['data'][$device][$keyword] = $rank

App Keywords + Stats API

# To retrive keywords with stats for Instagram in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/app/keywords/stats?appIds=com.instagram.android&apiKey=YOUR_API_KEY"
{
  "data": {
    "app2keywords": {
      "com.instagram.android": [
        {
          "keyword": "instagram photo",
          "inAutocomplete": 1,
          "hits": 250,
          "traffic": 82,
          "rank": 5,
          "hasRelated": 1
        },
        {
          "keyword": "instagrams photo apps",
          "inAutocomplete": 1,
          "hits": 250,
          "traffic": 79,
          "rank": 16,
          "hasRelated": 1
        }
       ]
     }
  }
}

This endpoint retrieves keywords (with stats) which the apps are ranked for under the top 250.

Definition

GET /v1/$platform/$country/app/keywords/stats

Credits per API request

100 credits per input app

Query Parameters

Parameter Required Description
appIds Y List of AppIds. Comma-separated. Up to 5 apps in a request.
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).
start N A cursor for use in pagination. default = 0.
count N A limit on the number of objects to be returned. Limit can range between 1 and 300 items. default = 300.

Response Format

$json['data']['app2keywords'][$appId][] = $keywordObject $json['data']['apps'][$appId][] = $appObjectDetail

All Rankings & Ratings API

# To retrive category ranking trends, search ranking trends and rating trend for Facebook Messenger in Google Play Store in the US.

curl "http://api.searchman.io/v1/android/us/app/trend?appId=com.facebook.orca&apiKey=YOUR_API_KEY"
{
  "data": {
    "searchRankingTrend": {
      "android": {
        "messanger": {
          "2014-03-04" : 1,
          "2014-03-05" : 1,
          "2014-03-06" : 2
        }
      }
    },
    "categoryRankingTrend": {
      "android": {
        "COMMUNICATION": {
          "free": {
            "2014-03-04" : 1,
            "2014-03-05" : 1,
            "2014-03-06" : 2
          }
        }
      }
    },
    "ratingTrend": {
      "2014-03-04" : 3089136,
      "2014-03-05" : 3193464,
      "2014-03-06" : 3193464
    }
  }
}

This endpoint retrieves historical trend of category ranking, search ranking and ratings for any app.

Definition

GET /v1/$platform/$country/app/trend

Credits per API request

30 credits per API request

Query Parameters

Parameter Required Description
appId Y AppId.

Response Format

$json['data']['searchRankingTrend'][$device][$keyword][$date] = $rank

$json['data']['categoryRankingTrend'][$device][$categoryId][$selection][$date] = $rank

$json['data']['ratingTrend'][$date] = $numRatings

Lookalike Apps API

# To retrive lookalike apps for Instagram in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/app/lookalike?appId=com.instagram.android&apiKey=YOUR_API_KEY"
{
  "data": {
      "1":"<appObject>",
      "2":"<appObject>",
      "3":"<appObject>",
      "4":"<appObject>",
      "5":"<appObject>"
  }
}

This endpoint retrieves lookalike apps given any app in the store. You can choose from 3 targets: “Also Installed Apps”, “Similar Apps (only for Google Play)”, or “Lookalike by SearchMan”.

Definition

GET /v1/$platform/$country/app/lookalike

Query Parameters

Parameter Required Description
appId Y AppId.
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).
start N A cursor for use in pagination. default = 1.
count N A limit on the number of objects to be returned. Limit can range between 1 and 25 items. default = 25.
target N lookalike (default), alsoInstalled or similar.

Response Format

$json['data'][$rank] = $appObject

Lookalike Apps API (ID Only)

# To retrive lookalike apps for Instagram in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/app/lookalike/ids?appId=com.instagram.android&apiKey=YOUR_API_KEY"
{
  "data": {
    "android": {
      "co.vine.android": 997749,
      "com.twitter.android": 990402,
      "com.facebook.katana": 818793,
      "com.google.android.apps.plus": 578733,
      "com.justunfollow.android": 502095,
      "com.pixlr.express": 481798
    }
  }
}

This endpoint retrieves lookalike apps given any app in the store. You can choose from 3 targets: “Also Installed Apps”, “Similar Apps (only for Google Play)”, or “Lookalike by SearchMan”.

Definition

GET /v1/$platform/$country/app/lookalike/ids

Credits per API request

5 credits per API request

Query Parameters

Parameter Required Description
appId Y AppId.
target N lookalike (default), alsoInstalled or similar.

Response Format

$json['data'][$device][$appId] = $similarityScore (if target is lookalike)

$json['data'][$device][$appId] = $position (if target is alsoInstalled or similar)

App Review API

# To retrive reviews for for Instagram in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/app/reviews?appId=com.instagram.android&apiKey=YOUR_API_KEY"
{
  "data": [
    {
      "id" : 1413244325167,
      "rating" : 1,
      "body" : "My instagram in crashing fix it",
      "reviewId" : "gp:AOqpTOG1I4HsR5QowGFz0BnhpDPqf-A2fdcMtu47u8LQ0Dg_dqf35ZQbqw8pThq178TniuhncD_9IvKCIuFZ2A",
      "version" : "6.8.1",
      "reply": "Hi, Thanks so much for the update! I wanted to let you know we're looking into adding a setting so you can have night mode always enabled. Great suggestion! Thanks for the patience while we build it out.",
      "replyId": 1454651973021,
      "replyTimestampEpoch": 1454651973,
      "replyTimestamp": "2016-02-05 05:59:33",
      "authorId": "106415544330127739411",
      "author": "Bethany Redway",
      "authorProfileImageUrl": "https://lh6.ggpht.com/-8anOxtWKjDY/AAAAAAAAAAI/AAAAAAAAAAA/TY3o8NEydcs/photo.jpg",
      "timestampEpoch" : "1413244325",
      "timestamp" : "2014-10-13 23:52:05"
    },
    {
      "id" : 1413244319283,
      "rating" : 5,
      "body" : "Love this app",
      "reviewId" : "gp:AOqpTOGtD40O8oq2BSHLQ_QFVLcGUwg8b0VZoQ74ioExNCOlh-eM_32k3VWU24gj2s4DZMA6SxxmD9Jkuqjhfg",
      "version" : "6.8.1",
      "reply": "Hi JT, Sorry to hear that! We've made some adjustments to learn music and I'd love to hear if you give it another shot and let me know if you still are running into trouble there. Thanks, I'm sure we can fix the issue.",
      "replyId": 1454652077811,
      "replyTimestampEpoch": 1454652077,
      "replyTimestamp": "2016-02-05 06:01:17",
      "authorId": "106415544330127739411",
      "author": "Bethany Redway",
      "authorProfileImageUrl": "https://lh6.ggpht.com/-8anOxtWKjDY/AAAAAAAAAAI/AAAAAAAAAAA/TY3o8NEydcs/photo.jpg",
      "timestampEpoch" : "1413244319",
      "timestamp" : "2014-10-13 23:51:59"
    }
  ]
}

This endpoint retrieves reviews given any app in the store.

Definition

GET /v1/$platform/$country/app/reviews

Credits per API request

1 credit per 20 count

Required credits = ceil [ count / 20 ]

Query Parameters

Parameter Required Description
appId Y AppId.
sort N mostrecent, mosthelpful, mostcritical, mostrecentCurrent (ios only), mosthelpfulCurrent (ios only), or mostcriticalCurrent (ios only). default = mostrecent.
start N A cursor for use in pagination. default = 0.
count N A limit on the number of objects to be returned. Limit can range between 1 and 100 items. default = 20.

Response Format

$json['data'][] = $reviewObject

Twitter Handles API

# To retrive twitter handles for HotelTonight in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/app/twitter?appId=com.hoteltonight.android.prod&apiKey=YOUR_API_KEY"
{
  "data": {
    "twitterHandles": [
      "hoteltonight"
    ]
  }
}

This endpoint retrieves twitter handles given any app in the store.

Definition

GET /v1/$platform/$country/app/twitter

Credits per API request

5 credits per API request

Query Parameters

Parameter Required Description
appId Y AppId.

Response Format

$json['data']['twitterHandles'][] = $twitterHandle

App Similarity API

# To retrive similarities between Instagram and Snapchat in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/similarity/apps?appIds1=com.instagram.android&appIds2=com.snapchat.android&apiKey=YOUR_API_KEY"
{
  "data": {
    "similarities": {
      "com.instagram.android": {
        "com.snapchat.android": 1208598
      }
    }
  }
}

This endpoint retrieves similarities between 2 (or more) apps in the store.

Definition

GET /v1/$platform/$country/similarity/apps

Credits per API request

1 credit per a pair of apps. (If you request 2 apps as $appIds1 and 3 apps as $appIds2, it would consume 6 credits.)

Query Parameters

Parameter Required Description
appIds1 Y List of AppIds. Comma-separated. Up to 10 apps
appIds2 Y List of AppIds. Comma-separated. Up to 10 apps
appIdFormat N appId (default, appId as appeared in the app stores) or bundleId
device N iPhone or iPad (if platform is ‘ios’); android (if platform is ‘android’).

Response Format

$json['data']['similarities'][$appId1][$appId2] = $similarityScore

Ad Targeting API (Keywords)

# To retrive related keywords of competitor apps of HotelTonight in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/targeting/keywords?targetBy=lookalike&appId=com.hoteltonight.android.prod&apiKey=YOUR_API_KEY"
{
  "data": {
    "app" : "<appObject>",
    "detail" : {
      "lookalike" : [
        "<appObject with keywords>",
        "<appObject with keywords>",
        "<appObject with keywords>"
      ],
      "alsoInstalledApps" : [
        "<appObject with keywords>",
        "<appObject with keywords>"
      ],
      "similarApps" : [
        "<appObject with keywords>",
        "<appObject with keywords>"
      ]
    },
    "summary": {
      "keywords": [
        "<keyword>",
        "<keyword>",
        "<keyword>",
        "<keyword>"
      ]
    }
  }
}

This endpoint retrieves related keywords of a) lookalike apps (given any app) or b) top apps (given any category) in the store, which you can use when you buy keyword targeting ads in Facebook, Twitter, Google Adwords.

Definition

GET /v1/$platform/$country/targeting/keywords

Credits per API request

500 credits per API request

Query Parameters

Parameter Required Description
targetBy Y lookalike or category
appId Y (*) AppId.
categoryId Y (**) Category Id, which you get from Category List API.
selection Y (**) Type of category ranking. free, top or grossing.

(*) appId is required if targetBy is lookalike.

(**) categoryId and selection are required if targetBy is category.

Response Format

$json['data']['app'] = $appObject or $json['data']['category'] = $categoryInformation

$json['data']['detail'][$source][] = $appObject with 'keywords'

$json['summary']['keywords'][] = $keyword

Ad Targeting API (Twitter)

# To retrive twitter handles of competitor apps of HotelTonight in Google Play in the US.

curl "http://api.searchman.io/v1/android/us/targeting/twitter?targetBy=lookalike&appId=com.hoteltonight.android.prod&apiKey=YOUR_API_KEY"
{
  "data": {
    "app" : "<appObject>",
    "detail" : {
      "lookalike" : [
        "<appObject with TwitterHandles>",
        "<appObject with TwitterHandles>",
        "<appObject with TwitterHandles>"
      ],
      "alsoInstalledApps" : [
        "<appObject with TwitterHandles>",
        "<appObject with TwitterHandles>"
      ],
      "similarApps" : [
        "<appObject with TwitterHandles>",
        "<appObject with TwitterHandles>"
      ]
    },
    "summary": {
      "twitterHandles": [
        "<twitterHandle>",
        "<twitterHandle>",
        "<twitterHandle>",
        "<twitterHandle>"
      ]
    }
  }
}

This endpoint retrieves twitter handles of a) lookalike apps (given any app) or b) top apps (given any category) in the store, which you can use when you buy Twitter Ads by using Twitter handles targeting.

Definition

GET /v1/$platform/$country/targeting/twitter

Credits per API request

500 credits per API request

Query Parameters

Parameter Required Description
targetBy Y lookalike or category
appId Y (*) AppId.
categoryId Y (**) Category Id, which you get from Category List API.
selection Y (**) Type of category ranking. free, top or grossing.

(*) appId is required if targetBy is lookalike.

(**) categoryId and selection are required if targetBy is category.

Response Format

$json['data']['app'] = $appObject or $json['data']['category'] = $categoryInformation

$json['data']['detail'][$source][] = $appObject with 'twitterHandles'

$json['summary']['twitterHandles'][] = $twitterHandle

Errors

The API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is invalid
401 Unauthorized – Your API key is wrong
403 Forbidden – The requested is hidden for administrators only
404 Not Found – The specified endpoint could not be found
409 Exceeded usage limit – You’ve hit the usage limit of your plan.
429 Too Many Requests – You’re requesting too many requests! Slown down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.