google-play/
app-rankings

既知のランキングURLから公開Google Playのカテゴリ別ランキングを収集し、順位、アプリ情報、ストアのメタデータ、メディア、取得時の情報を含む正規化アプリレコードとして返します。

Google Play App Rankings API

カテゴリURLで指定
正規化アプリレコード
結果単位の課金
結果1件あたり0.15クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

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つ以上送信して非同期タスクを追跡し、成功後に正規化されたランキングレコードを読み取ります。

  1. 必要なマーケットと収集対象のランキング面がすでにURLに含まれている、公開play.google.comのカテゴリURLまたはランキングURLを選びます。
  2. urls と任意の results_limit を /v1/google-play/app-rankings に POST し、返された task_id を保存します。
  3. status が succeeded または failed になるまで /v1/tasks/{task_id} をポーリングします。タスクが待機中または実行中の間は結果を取得できません。
  4. 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=50

Google 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クレジットとなり、未使用の見積もり分は返金されます。

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から公開アプリレビューを取得します。国を任意で指定でき、正規化された本文、レビュー投稿者、評価、日時、アプリの参照の各フィールドを返します。

他のプラットフォームを見る

Google Playのデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

Google Play App Rankings API — よくある質問

Google Play App Rankings APIは、公開Google PlayのカテゴリランキングURLを収集し、取得できた順位、アプリ情報、ストアのメタデータ、メディア、取得元、取得日時を含む正規化 AppItem レコードとして返すプログラムインターフェースです。

公開play.google.comランキングURLの空でない配列を送信します。サブドメインも受け付けますが、すべてのパスに /store/apps/collection/ または /store/apps/category/ が含まれている必要があります。アプリ詳細ページや無関係なパスは拒否されます。

できません。リクエストで受け付けるのは urls と任意の results_limit のみです。マーケット、コレクション、カテゴリの指定は、送信するGoogle PlayのURL自体に含めておく必要があります。

results_limit には1〜2000を指定でき、デフォルトは100です。タスク全体での取得件数と保存結果の上限となり、事前引き当てに使う初回の結果件数見積もりを決めます。複数のURLは順番に処理され、タスクの残り件数枠が割り当てられます。

できません。プロバイダーがデータセットの収集を完了してから、SocQが結果を公開します。next_cursor は、成功したタスクですでに保存されている正規化レコードを読み進めるためだけのものです。

AppItem の結果には、ID、platform、resource、type、URL、タイムスタンプ、app_id、name、text、developer、category、rating、reviews_count、installs、price、rank、media の固定フィールドが含まれます。ソース側で取得できない任意の値は null のままになります。

基本料金0クレジット、保存された結果1件につき0.15 SocQクレジットです。SocQは results_limit またはデフォルトの見積もり100件分を事前に引き当て、実際の結果件数で精算し、未使用の見積もり分を返金します。結果が0件の場合の精算額は0です。