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)のみ対応しています。

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

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

国一覧

国名	$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はアプリを一覧表示するのに必要なだけの情報を含みます。

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

`appObject`と`appObjectDetail`の両方に含まれる要素

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の詳細

# 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

Category Ranking Trends API

# 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

Search Ranking Trends API

# 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における「人気検索」キーワード一覧を返します。

このAPIは、現時点でiosのみに対応しています。

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における「人気検索」キーワード一覧＋各キーワードの詳細情報を返します。

このAPIは、現時点でiosのみに対応しています。

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は、入力キーワードに対しての関連キーワード一覧を返します。

このAPIは、現時点でiosのみに対応しています。

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は、入力キーワードに対しての関連キーワード一覧＋各キーワードの詳細情報を返します。

このAPIは、現時点でiosのみに対応しています。

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 (targetがlookalikeの場合)

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

$similarityScoreは、入力アプリとそれぞれのアプリとの類似度を表します。$similarityScoreが大きいほど、2つのアプリが似ているということを意味します。

$positionは、各アプリがそれぞれのセクションで何番目に表示されるかを表します。

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の場合、categoryIdとselectionが必須です。

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の場合、categoryIdとselectionが必須です。

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.

App Store APIの概要

認証（Authentication）

API Creditsに関して

入力と出力 (In & Out)

Parameters

国一覧 (Available Countries)

国一覧

App Objectについて

2種類のapp object

appObjectとappObjectDetailの両方に含まれる要素

appObjectDetailのみに含まれる要素

Keyword Objectについて

keywordObjectに含まれる要素

APIの詳細

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

`appObject`と`appObjectDetail`の両方に含まれる要素

`appObjectDetail`のみに含まれる要素

`keywordObject`に含まれる要素