Google Play App Rankings
Google PlayのランキングURLは収集対象のカテゴリやランキング面を指定し、results_limit は取得件数を1〜2000件の範囲で制御します。保存される各結果は AppItem の仕様に従うため、順位を、取得できたパッケージ識別子、デベロッパー、カテゴリ、評価、レビュー件数、インストール数、価格、メディア、取得元URL、取得日時と並べて分析できます。
Google Play App Rankings API の主な機能
- ランキングURLの一括送信国やカテゴリを個別のフィールドで指定する代わりに、公開されているplay.google.comのカテゴリページまたはランキングページを空でない urls 配列で送信します。
- Google PlayランキングURLの検証play.google.comとそのサブドメインのうち、パスに /store/apps/collection/ または /store/apps/category/ を含むURLのみを受け付けます。
- 上限付きのランキング収集results_limit は1〜2000の範囲で指定します。省略した場合は100となり、これは課金見積もりおよびプロバイダー側の取得件数のデフォルト値でもあります。
- 正規化されたアプリ順位rank を、取得できた app_id、name、developer、category、rating、reviews_count、installs、price、media、公開ソースのメタデータとともに、1つの AppItem 形式で読み取れます。
- 非同期データセットワークフロー送信したURL行をもとにプロバイダー側で非同期データセットが実行され、SocQが正規化レコードを保存し、共通のタスク読み取りAPIからタスクの状態を返します。
- 保存済み結果のカーソル成功後は、タスク読み取りAPIが返す不透明な next_cursor と1〜500の limit でSocQのレコードをページ送りします。このカーソルはGoogle Playやプロバイダーのページトークンではありません。
- 実際の結果件数による精算SocQは指定またはデフォルトの見積もり件数分を事前に引き当て、保存された結果1件につき0.15クレジットで精算し、未使用の見積もり分を返金します。結果が0件の場合は基本料金0クレジットで精算されます。
Google Play App Rankings API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | 必須。公開Google PlayランキングURLの空でない配列です。各URLはplay.google.comまたはそのサブドメインを使用し、パスに /store/apps/collection/ または /store/apps/category/ を含む必要があります。国やカテゴリを独立したフィールドとして指定することはできません。 |
results_limit | 任意 | 任意。1〜2000の正の整数です。デフォルトは100で、タスク全体での取得件数と保存レコード数の上限となり、初回の課金見積もりにも使われます。入力URLは順番に処理され、タスクの残り件数枠が割り当てられます。 |
Google Play App Rankings API の使い方
既知のGoogle PlayランキングURLを1つ以上送信して非同期タスクを追跡し、成功後に正規化されたランキングレコードを読み取ります。
- 必要なマーケットと収集対象のランキング面がすでにURLに含まれている、公開play.google.comのカテゴリURLまたはランキングURLを選びます。
- urls と任意の results_limit を /v1/google-play/app-rankings に POST し、返された task_id を保存します。
- status が succeeded または failed になるまで /v1/tasks/{task_id} をポーリングします。タスクが待機中または実行中の間は結果を取得できません。
- data.results.items を読み取り、has_more が true の場合のみ next_cursor で続きを取得します。
curl -X POST "https://api.socq.ai/v1/google-play/app-rankings" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://play.google.com/store/apps/collection/topselling_free"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Continue with GET /v1/tasks/{task_id}?cursor={next_cursor}&limit=50Google Play App Rankings API の主なユースケース
- カテゴリ別ランキングのスナップショット: rank と collected_at をあわせて保存し、既知のGoogle Playランキングを別々に収集したスナップショット同士で比較します。
- ランキング上位アプリの発見: 厳選したカテゴリURL群を正規化アプリレコードに変換し、レビュー、タグ付け、下流のカタログ情報補完に活用します。
- ポートフォリオの順位チェック: 取得できた app_id と developer フィールドを社内のポートフォリオと照合し、表示名の一致だけに頼らずに各順位を確認します。
- 複数回の収集にまたがるストア分析: 固定された AppItem フィールドをデータウェアハウスに取り込み、null許容の評価、レビュー件数、インストール数、価格、順位を収集回をまたいで比較できるようにします。
Google Play App Rankings API 活用のヒント
- アプリ詳細ページ、検索語、国コード、カテゴリ名ではなく、公開Google PlayのカテゴリURLまたはランキングURLを使用してください。このリクエストに指定できるのは urls と results_limit のみです。
- パスに /store/apps/collection/ または /store/apps/category/ を含むplay.google.comのURLを使用してください。アプリ詳細ページや無関係なパスは、収集開始前の検証でエラーになります。
- 複数のURLを入力した場合、results_limit はタスク全体で共有されます。URLは順番に処理され、それぞれ残りの件数枠のみが割り当てられるため、ランキングごとに独立した件数枠が必要な場合はタスクを分けてください。
- アプリのメタデータは null になりうるものとして扱ってください。評価、レビュー件数、インストール数、価格、メディアが常に入っていると想定せず、取得できた場合は app_id、url、rank、collected_at を保持してください。
- ソース側のカーソルは送信しないでください。成功を待ってから、data.results 内で返される不透明な next_cursor のみを使ってSocQの保存済みレコードをページ送りしてください。
- 予算は送信時の results_limit をもとに見積もってください。最終的なクレジットは実際に保存された結果件数に応じて1件あたり0.15クレジットとなり、未使用の見積もり分は返金されます。
関連API
Google Play App Rankings API 以外に別の種類の公開Google Playデータが必要な場合は、これらのAPIをご利用ください。
- Google Play App Detail API — 既知のアプリURLから、Google Playの公開掲載情報を正規化して取得します。アプリ情報、ストア掲載文、デベロッパー、カテゴリ、表示中の指標、価格、メディア、取得情報を含みます。
- Google Play App Reviews API — play.google.comのURLから公開アプリレビューを取得します。国を任意で指定でき、正規化された本文、レビュー投稿者、評価、日時、アプリの参照の各フィールドを返します。