NAV
shell

App Store APIの概要

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

App Store API by SearchManは、iOS App StoreやGoogle Play Storeの情報を簡単に取得できるようにすることを目的に設計されています。カテゴリー順位、検索順位、アプリ詳細情報などあらゆるストアの情報をAPI経由で取得できます。

APIは全てREST形式で、レスポンスはJSON形式です。

認証(Authentication)

# サンプルリクエスト

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

APIへのアクセス認証はAPI Keyによって行われます。API KeyをGETパラメーターとしてURLに付与してください。また、API Keyは公開しないようにしてください。

API Creditsに関して

各APIリクエストには、それぞれ異なる “credit” が必要です。こちらで、それぞれのAPIが1リクエストあたりに必要なcreditをご覧いただけます。多くのAPIは1リクエストあたり1クレジットを消費します。1クレジット以上必要なAPIに関しては、このドキュメント(下記)にも記載されています。

入力と出力 (In & Out)

# 出力には 'status', 'response_msec', 'data'が含まれます:
{
 "status": 200,
 "response_msec": "123",
 "data": {

  }
}
# 'status' が200でない場合、'msg'(エラーの理由)も出力されます:
{
 "status": 404,
 "response_msec": "123",
 "msg": "not found"
}

APIのURLは以下のように、$platform$countryを含みます。

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

Parameters

Parameter Default
$platform Apple App Storeの場合はiosもしくは、Google Playの場合はandroid
$country ISO 3166-1 alpha-2 country codeに準拠した国コード。

以下の表に、他にもよく使うパラメーターを整理します。

Parameter Default
$device iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。
$categoryId 各App StoreのカテゴリーID。Category List API より取得可能。
$selection カテゴリーランキングの種類。free(無料), paid(有料)あるいはgrossing(売上)。
$appId アプリのID。iosの場合は9桁の数字、androidの場合はbundleId。

国一覧 (Available Countries)

多くのAPIは、現時点ではus (USA)とjp (日本)にのみ対応しています。

下記のAPIは、表にある全ての$countryのデータをご利用いただけます。

国一覧

国名 $country
アメリカ us
日本 jp
イギリス gb
カナダ ca
ブラジル br
中国 cn
ロシア ru
インド in
韓国 kr
メキシコ mx
台湾 tw
ドイツ de
フランス fr
オーストラリア au
インドネシア id
トルコ tr
タイ th
コロンビア co
アルゼンチン ar

App Objectについて

# Facebook Messanger(Google Play, US)の<appObjectDetail>の例
{
  "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種類のapp object

APIによって、2種類のappObjectを使い分けています。 appObjectDetailは当該アプリの全ての詳細情報を含みます。 他方、appObjectはアプリを一覧表示するのに必要なだけの情報を含みます。

アプリ詳細情報APIappObjectDetailを返し、その他のAPIはappObjectを返します。

appObjectappObjectDetailの両方に含まれる要素

Parameter Description
appId アプリID
appName アプリの名前
primaryCategoryId 主なカテゴリーID
iconUrl アイコンのURL (100x100 pixel)
price 価格
currency 通貨
formattedPrice 表示用価格
version 最新バージョン
fileSizeBytes アプリのファイルサイズ(現在iosのみ)
releaseDate iosアプリの場合は、アプリのリリース日時、androidの場合は、最新バージョンの公開日時
studioId アプリ開発社のID
studioName アプリ開発社名
studioUrl アプリ開発社のウェブサイトURL
hasInAppPurchases アプリ内課金がある場合は1
userRatingCount Ratingsの数
commentCount レビューの数(現在androidのみ)
averageUserRating ★の平均(1から5)
starRatings それぞれの★のRatingsの数(配列)

appObjectDetailのみに含まれる要素

Parameter Description
bundleId bundleId( iosのみ)
numDownloads ダウンロード数(現在androidのみ)
categoryIds カテゴリーID(複数、配列)
description アプリ説明文
releaseNotes 最新バージョンのリリースノート
permissions 各アプリが要求するパーミッション・アクセス許可(現在androidのみ)
screenshotUrls スクリーンショットのURL(配列)
ipadScreenshotUrls スクリーンショットのURL(配列、現在はiPad対応アプリのみ)
videoUrl ビデオURL(現在androidのみ)
videoScreenUrl ビデオの画像URL(現在androidのみ)
userRatingCountCurrent 現在のバージョンのRatingsの数(現在iosのみ)
averageUserRatingCurrent 現在のバージョンの★の平均(1から5、現在iosのみ)
starRatingsCurrent 現在のバージョンのそれぞれの★のRatingsの数(配列、現在iosのみ)
similarAppIds Similar AppsのアプリID一覧(現在androidのみ)
alsoInstalledAppIds 「このアプリをインストールしている人はこのアプリもインストールしています」のアプリID一覧(配列)

Keyword Objectについて

# "dating apps"というキーワードの<keywordObject>の例 (Google Play, US)
{
  "keyword": "dating apps",
  "inAutocomplete": 1,
  "hits": 2159,
  "traffic": 82,
  "hasRelated": 1
}

keywordObjectに含まれる要素

Parameter Description
keyword キーワード
inAutocomplete 当該キーワードが「autocomplete(入力補完候補)」に出現するか否か (1=true, 0=false)。「autocomplete(入力補完候補)」に出現するキーワードは検索回数が多い傾向にあります。
traffic App Store or Google Play Storeでの推計検索回数 (0 to 100)
hits 検索ヒット数(Google Playのヒット数は最大250)
hasRelated 当該キーワードに対して「Related Keywords」が存在するか否か (1=true, 0=false)。「Related Keywords」が存在するキーワードは検索回数が多い傾向にあります。現在、ios & usの組み合わせでのみデータが存在。

APIの詳細

Category List API

# Google Play, 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"
    }
  }
}

このAPIはカテゴリー一覧を返します。

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

# Google Play, 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>"
  }
}

このAPIは、カテゴリー、セレクションごとの上位アプリ一覧を返します。

Definition

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

Query Parameters

Parameter Required Description
categoryId Y 各App StoreのカテゴリーID。Category List API より取得可能。
selection Y カテゴリーランキングの種類。free(無料), paid(有料)あるいはgrossing(売上)。
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。
start N 開始位置。デフォルト = 1。
count N 件数(1から25の間の整数)デフォルト = 25。

Response Format

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

Category Ranking API (ID Only)

# Google Play, 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"
      }
    }
  }
}

このAPIは、カテゴリーごとの上位アプリ一覧(appIdのみ)を返します。

Definition

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

Credits per API request

5 credits per API request

Query Parameters

Parameter Required Description
categoryId Y 各App StoreのカテゴリーID。Category List API より取得可能。

Response Format

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

# Google Play, 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
        }
      }
    }
  }
}

このAPIは、カテゴリー、セレクションごとの上位アプリ一覧の時系列トレンドを返します。

Definition

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

Credits per API request

10 credits per API request

Query Parameters

Parameter Required Description
categoryId Y 各App StoreのカテゴリーID。Category List API より取得可能。

Response Format

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

Category Ranking by Apps API

# Google Play, USにおける「Facebook」「Twitter」の2016-02-14から2016-02-15までのカテゴリー順位を取得する例

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

このAPIは、特定のアプリのカテゴリー順位の時系列トレンドを返します。

Definition

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

Credits per API request

10 credits per day per AppId

(例. 2アプリの5日間分のカテゴリー順位をリクエストすると、100 API creditsを消費します。)

Query Parameters

Parameter Required Description
appIds Y アプリのID(最大5個まで複数可)。カンマ区切り。
startDate Y 開始日 (YYYY-mm-dd)
endDate Y 終了日 (YYYY-mm-dd). endDate - startDate は31日以内である必要あり。

Response Format

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

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

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

Search API

# Google Play, 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>"
  }
}

このAPIは、App Storeの検索結果を返します。

Definition

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

Query Parameters

Parameter Required Description
q Y クエリ。urlencodeが必要。
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。
start N 開始位置。デフォルト = 1。
count N 件数(1から25の間の整数)デフォルト = 25。

Response Format

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

Search API (ID Only)

# Google Play, 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"
  }
}

このAPIは、App Storeの検索結果(appIdのみ)を返します。

Definition

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

Credits per API request

5 credits per API request

Query Parameters

Parameter Required Description
q Y クエリ。urlencodeが必要。
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。

Response Format

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

# Google Play, 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
      }
    }
  }
}

このAPIは、App Storeの検索順位の時系列トレンドを返します。

Definition

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

Credits per API request

10 credits per API request

Query Parameters

Parameter Required Description
q Y クエリ。urlencodeが必要。

Response Format

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

# iPhone, USにおける「人気検索」キーワード(Trending Keywords)一覧を取得する例

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

このAPIは、App Storeにおける「人気検索」キーワード一覧を返します。

Definition

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

Credits per API request

1 credit per day (例. 3日間分の「人気検索」キーワードをリクエストすると、3 API creditsを消費します。)

Query Parameters

Parameter Required Description
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。
start N 開始時刻のタイムスタンプ (Unix epoch)。
end N 終了時刻のタイムスタンプ (Unix epoch)。end - startは7日以内である必要あり。

Response Format

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

# iPhone, USにおける「人気検索」キーワード(Trending Keywords)一覧+キーワードの詳細情報を取得する例

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

このAPIは、App Storeにおける「人気検索」キーワード一覧+各キーワードの詳細情報を返します。

Definition

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

Credits per API request

10 credits per day (例. 3日間分の「人気検索」キーワードをリクエストすると、30 API creditsを消費します。)

Query Parameters

Parameter Required Description
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。
start N 開始時刻のタイムスタンプ (Unix epoch)。
end N 終了時刻のタイムスタンプ (Unix epoch)。end - startは7日以内である必要あり。

Response Format

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

Autocomplete API

# Google Play, USにおける「photo」と入力した場合の自動補完キーワード一覧を取得する例

curl "http://api.searchman.io/v1/android/us/search/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"
  ]
}

このAPIは、入力キーワードに対しての自動補完キーワード一覧を返します。

Definition

GET /v1/$platform/$country/search/hints

Query Parameters

Parameter Required Description
q Y クエリ。urlencodeが必要。
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。

Response Format

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

Autocomplete + Stats API

# Google Play, USにおいて「dating」「photo」と入力した場合の自動補完キーワード一覧+各キーワードの詳細情報を取得する例

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

このAPIは、入力キーワードに対しての自動補完キーワード一覧+各キーワードの詳細情報を返します。

Definition

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

Credits per API request

10 credits per input query

Query Parameters

Parameter Required Description
keywords Y 入力クエリ(複数可・最大5クエリまで) Jsonエンコード、urlencodeが必要。
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。

Response Format

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

# iPhone, USにおける「photo」と入力した場合の関連キーワード一覧を取得する例

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

このAPIは、入力キーワードに対しての関連キーワード一覧を返します。

Definition

GET /v1/$platform/$country/search/related

Query Parameters

Parameter Required Description
q Y クエリ。urlencodeが必要。
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。

Response Format

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

# iPhone, USにおいて「dating」「photo」と入力した場合の関連キーワード一覧+各キーワードの詳細情報を取得する例

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

このAPIは、入力キーワードに対しての関連キーワード一覧+各キーワードの詳細情報を返します。

Definition

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

Credits per API request

10 credits per input query

Query Parameters

Parameter Required Description
keywords Y 入力クエリ(複数可・最大5クエリまで) Jsonエンコード、urlencodeが必要。
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。

Response Format

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

App Metadata API

# Google Play, USにおける「Facebook Messanger」「Pandora」のアプリ詳細情報を取得する例

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

このAPIは、アプリ詳細情報を返します。(複数アプリを一度に取得可能)

Definition

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

Credits per API request (“リアルタイム取得"をしない場合)

appIds 5つごとに1 credit

Credit数 = ceil [ count(appIds) / 5 ]

Credits per API request ("リアルタイム取得"をする場合)

appIds 1つごとに10 credits

Required credits = count(appIds) * 10

Query Parameters

Parameter Required Description
appIds Y アプリのID(複数可・カンマ区切り)。realtimeFetch=0の場合、最大100個まで、realtimeFetch=1の場合、最大5つまで。
realtimeFetch N リアルタイムデータを取得する場合 1。デフォルト = 0。

Response Format

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

App Registration API

# Google Play, USにおける「Pandora」のアプリを登録する例

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

このAPIは、(未だ情報が取得されていない)アプリIDを入力すると、アプリをデータストレージに追加した上で、アプリの情報を返します。

Definition

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

Query Parameters

Parameter Required Description
appId Y アプリのID

Response Format

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

App Keywords API

# Google Play, USにおける「Instagram」に関連するキーワードを取得する例

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

このAPIは、入力されたアプリに関連するキーワード一覧を返します。キーワードは、 a) アプリ名、説明文など公開情報に含まれるキーワード、かつ b) 250位以内にランクインしているキーワードを抽出します。

Definition

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

Query Parameters

Parameter Required Description
appId Y アプリのID。

Response Format

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

App Keywords + Stats API

# Google Play, USにおける「Instagram」に関連するキーワード+各キーワードの詳細を取得する例

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

このAPIは、入力されたアプリに関連するキーワード一覧+各キーワードの詳細情報を返します。キーワードは当該アプリが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 アプリのID(最大5個まで複数可)。カンマ区切り。
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。
start N 開始位置。デフォルト = 0。
count N 件数(1から300の間の整数)デフォルト = 300。

Response Format

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

All Rankings & Ratings API

# Google Play, USにおける「Facebook Messanger」のカテゴリー順位トレンド、検索順位トレンド、レーティング数トレンドを取得する例

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

このAPIは、入力されたアプリのカテゴリー順位、検索順位、レーティング数の時系列トレンドを返します。

Definition

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

Credits per API request

30 credits per API request

Query Parameters

Parameter Required Description
appId Y アプリのID。

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

# Google Play, USにおける「Instagram」に類似するアプリの一覧を取得する例

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

このAPIは、入力されたアプリに類似するアプリ一覧を返します。3種類の「類似」の定義があります: "カスタマーはこんな商品も購入(Also Installed)”, “類似のアイテム(Similar, Google Playのみ)”, or “Lookalike by SearchMan”.

Definition

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

Query Parameters

Parameter Required Description
appId Y アプリのID。
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。
start N 開始位置。デフォルト = 1。
count N 件数(1から25の間の整数)デフォルト = 25。
target N lookalike (デフォルト), alsoInstalled or similar.

Response Format

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

Lookalike Apps API (ID Only)

# Google Play, USにおける「Instagram」に類似するアプリの一覧を取得する例

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

このAPIは、入力されたアプリに類似するアプリ一覧(appIdのみ)を返します。3種類の「類似」の定義があります: “カスタマーはこんな商品も購入(Also Installed)”, “類似のアイテム(Similar, 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 アプリのID。
target N lookalike (デフォルト), alsoInstalled or similar.

Response Format

$json['data'][$device][$appId] = $similarityScore (targetlookalikeの場合)

$json['data'][$device][$appId] = $position (targetalsoInstalled or similarの場合)

App Review API

# Google Play, USにおける「Instagram」に対するレビュー一覧を取得する例

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

このAPIは、入力されたアプリに対するレビュー一覧を返します。

Definition

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

Credits per API request

count 20件ごとに1 credit

Credit数 = ceil [ count / 20 ]

Query Parameters

Parameter Required Description
appId Y アプリのID。
sort N ソート順。mostrecent, mosthelpful, mostcritical, mostrecentCurrent (ios only), mosthelpfulCurrent (ios only), or mostcriticalCurrent (ios only). デフォルト = mostrecent.
start N 開始位置。デフォルト = 0。
count N 件数(1から100の間の整数)デフォルト = 20。

Response Format

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

Twitter Handles API

# Google Play, USにおける「HotelTonight」のTwitterアカウントを取得する例

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

このAPIは、入力されたアプリのTwitterアカウントを返します。

Definition

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

Credits per API request

5 credits per API request

Query Parameters

Parameter Required Description
appId Y アプリのID。

Response Format

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

App Similarity API

# Google Play, USにおけるInstagramとSnapchatの類似度を取得する例

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

このAPIは任意の2アプリの間の意味的な類似度を返します。

Definition

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

Credits per API request

1 credit per a pair of apps. (例: $appIds1に2アプリ、$appIds2に3アプリリクエストする場合、6 credits消費されます)

Query Parameters

Parameter Required Description
appIds1 Y アプリのID(最大10個まで複数可)。カンマ区切り。
appIds2 Y アプリのID(最大10個まで複数可)。カンマ区切り。
appIdFormat N appId (デフォルト, ストアのアプリID) or bundleId
device N iPhoneあるいはiPad (platformが‘ios’の場合); android (platformが'android'の場合)。

Response Format

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

Ad Targeting API (Keywords)

# Google Play, USにおける「HotelTonight」の競合アプリの関連キーワードを全て取得する例

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

このAPIは、a) 入力されたアプリとその競合アプリの関連キーワード、あるいはb) 入力されたカテゴリーの上位アプリの関連キーワードを全て返します。これらのキーワード情報は、キーワードターゲティング広告(Facebook, Twitter, Adwords, Yahoo検索連動広告など)で広告キャンペーンを作成する際にご利用いただけます。

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 (*) アプリのID。
categoryId Y (**) 各App StoreのカテゴリーID。Category List API より取得可能。
selection Y (**) カテゴリーランキングの種類。free(無料), paid(有料)あるいはgrossing(売上)。

(*) targetByがlookalikeの場合、appIdが必須です。

(**) targetByがcategoryの場合、categoryIdselectionが必須です。

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

このAPIは、a) 入力されたアプリの競合アプリのTwitterアカウント、あるいはb) 入力されたカテゴリーの上位アプリのTwitterアカウントを全て返します。これらのTwitterアカウント情報は、Twitter広告をTwitterアカウントターゲティング付きで購入する際にご利用いただけます。

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 (*) アプリのID。
categoryId Y (**) 各App StoreのカテゴリーID。Category List API より取得可能。
selection Y (**) カテゴリーランキングの種類。free(無料), paid(有料)あるいはgrossing(売上)。

(*) targetByがlookalikeの場合、appIdが必須です。

(**) targetByがcategoryの場合、categoryIdselectionが必須です。

Response Format

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

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

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

エラーコード (Errors)

本APIで利用するエラーコードは以下の通りです。

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.