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

Some APIs are available only for us (USA).

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

Category List API
Category Ranking
Category Ranking API (ID Only)
Category Ranking by Apps API
Search API
Search API (ID Only)
Autocomplete API
Related Keywords API
App Metadata API (Only if realtimeFetch=1)
App Review API
Twitter Handles API

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 `appId`s of the similar apps. Currently `android` only.
alsoInstalledAppIds	Array. List of the `appId`s 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

# 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

Category Ranking Trends API

# 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

Search Ranking Trends API

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

This API is only avaliable for ios at the moment.

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.

This API is only avaliable for ios at the moment.

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.

This API is only avaliable for ios at the moment.

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.

This API is only avaliable for ios at the moment.

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

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)

$similarityScore represents how similar each app is to the app in the parameter. The bigger $similarityScore is, the more similar the pair of 2 apps is.

$position represents the position of each app in each target section.

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.

SearchMan’s App Store API

Authentication

API Credits

Request & Response

Parameters

Available Countries

List of Available Countries

App Object

2 types of app objects

Common Elements in appObject & appObjectDetail

Elements only in appObjectDetail

Keyword Object

Elements in keywordObject

API Details

Category List API

Definition

Query Parameters

Response Format

Category Ranking API

Definition

Query Parameters

Response Format

Category Ranking API (ID Only)

Definition

Credits per API request

Query Parameters

Response Format

Category Ranking Trends API

Definition

Credits per API request

Query Parameters

Response Format

Category Ranking by Apps API

Definition

Credits per API request

Query Parameters

Response Format

Search API

Definition

Query Parameters

Response Format

Search API (ID Only)

Definition

Credits per API request

Query Parameters

Response Format

Search Ranking Trends API

Definition

Credits per API request

Query Parameters

Response Format

Trending Keywords API

Definition

Credits per API request

Query Parameters

Response Format

Trending Keywords + Stats API

Definition

Credits per API request

Query Parameters

Response Format

Autocomplete API

Definition

Query Parameters

Response Format

Autocomplete + Stats API

Definition

Credits per API request

Query Parameters

Response Format

Related Keywords API

Definition

Query Parameters

Response Format

Related Keywords + Stats API

Definition

Credits per API request

Query Parameters

Response Format

App Metadata API

Common Elements in `appObject` & `appObjectDetail`

Elements only in `appObjectDetail`

Elements in `keywordObject`