Apple App Store Rankings
Apple App Storeのカテゴリ別ランキングは、順位、アプリの識別情報、開発者、カテゴリ、評価、レビュー数、価格、アートワークのフィールドを持つ、順序付きの公開アプリリストです。これらのレコードは、ランキングのモニタリング、順位付きカタログの情報補完、各順位に付随する公開ストア情報の比較に活用できます。
Apple App Store Rankings API の主な機能
- カテゴリ別ランキングURLからの検出1つ以上の公開apps.apple.comカテゴリページまたはランキングURLを入力として、それらのページに表示される順位付きアプリレコードを検出します。
- 順位とアプリの識別情報取得できた各ソース上の順位をアプリID、名前、公開ストアURLとあわせて保持し、順序付きの結果を識別できるようにします。
- 開発者とカテゴリの情報正規化された各アプリケーションレコードとともに、取得可能な開発者名またはパブリッシャー名とストアカテゴリを返します。
- 表示中のストア指標公開ランキングの結果に表示されている場合は、評価、レビュー数、構造化された価格を含めます。
- 説明文とアートワーク取得可能なアプリのテキストとメディア参照を、結果の他の部分と同じ固定アプリスキーマで保持します。
Apple App Store Rankings API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | 必須。公開Apple App StoreランキングURLの配列です。解析後のホスト名はすべてapps.apple.comまたはそのサブドメインで、パスには必ず /charts/ を含める必要があります。 |
results_limit | 任意 | 任意。タスク全体の上限を1〜2,000の範囲で指定します。このフィールドを省略した場合、バックエンドは100を使用します。 |
Apple App Store Rankings API の使い方
公開Apple App Storeのカテゴリ別ランキングURLから始めて結果全体の上限を設定し、タスクの成功後に保存された正規化アプリレコードを読み取ります。
- パスに /charts/ を含む公開apps.apple.comランキングURLを1つ以上入力します。用意されているサンプルはバックエンドの検証ルールを満たしています。
- results_limit を1〜2,000の範囲で指定するか、省略してバックエンドのデフォルトである100件を使用します。
- ペイロードを /v1/apple-app-store/rankings に POST して task_id を保存し、タスクが成功または失敗するまで /v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取り、has_more が true の間は next_cursor を使って保存済み結果の次のページを取得します。
curl -X POST "https://api.socq.ai/v1/apple-app-store/rankings" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://apps.apple.com/us/iphone/charts/6007"],"results_limit":3}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueApple App Store Rankings API の主なユースケース
- カテゴリ別ランキングのモニタリング: 繰り返し実行した結果から順位、アプリの識別情報、collected_at を保存し、特定時点のランキングのスナップショットを区別します。
- 順位付きアプリカタログの情報補完: ランキングで検出したエントリに、アプリID、名前、開発者、カテゴリ、ストアURL、説明文、アートワークを追加します。
- ストア情報の比較: 同じカテゴリ別ランキングから返されたアプリ間で、取得可能な順位、評価、レビュー数、価格を比較します。
Apple App Store Rankings API 活用のヒント
- パスに /charts/ を含むapps.apple.comランキングURLを使用してください。個別のアプリ詳細URLや無関係なパスは、収集開始前の検証で失敗します。
- results_limit は urls に複数のランキングが含まれていてもタスクに保存される行の総数を制限するため、ランキングごとに個別の上限が必要な場合はタスクを分けて送信してください。
- next_cursor は保存済みのSocQ結果をページ単位で読み取るためだけに使ってください。プロバイダーの別のランキングページを要求したり、元の結果上限を拡張したりするものではありません。
- タスク内では保存レコードがアプリIDまたはソースURLで重複排除されるため、ランキングごとの出現をすべて保持したい場合は、重複するランキングを別々に実行してください。
- 説明文、評価、レビュー数、価格、アートワークなどの任意フィールドは null になり得るものとして扱い、後続の表示では空の値を省略してください。
関連API
Apple App Store Rankings API 以外に別の種類の公開Apple App Storeデータが必要な場合は、これらのAPIをご利用ください。
- Apple App Store App Detail API — 既知のApp Store掲載URLから、正規化された公開アプリ情報、説明メタデータ、デベロッパーとカテゴリの情報、表示中の評価、価格、メディアを取得します。
- Apple App Store App Reviews API — 既知のapps.apple.com URLから公開アプリレビューを取得し、正規化された本文、評価、レビュー投稿者の詳細、タイムスタンプ、アプリの参照を返します。