Apple App Store Rankings
Apple App Store 分类排名是按位置排列的公开应用列表，包含排名、应用标识、开发者、分类、评分、评价数、价格和图片等信息。这些记录适合观察榜单快照、补全排名应用目录，以及比较同一分类中各位置对应的公开商店信息。
主要特性
- 按分类榜单 URL 发现应用输入一个或多个公开 apps.apple.com 分类或排名页面 URL，获取这些页面公开的排名应用记录。
- 排名与应用标识关联将可获得的来源排名与应用 ID、名称和公开商店 URL 一同保留，便于识别每个位置对应的应用。
- 开发者与分类信息每条标准化应用记录可返回开发者或发行方名称以及商店分类。
- 公开商店指标榜单结果提供数据时，记录评分、评价数量和结构化价格字段。
- 应用说明与图片把可获得的应用说明和媒体引用纳入同一套固定应用响应结构。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 必填的公开 Apple App Store 榜单 URL 数组；每项解析出的主机名必须是 apps.apple.com 或其子域名，且路径必须包含 /charts/。 |
results_limit | 可选 | 可选的任务总结果上限，可填写 1 至 2,000；省略时 backend 使用 100。 |
如何使用
从公开 Apple App Store 分类榜单 URL 开始，设置任务总结果上限，并在任务成功后读取已保存的标准化应用记录。
- 输入一个或多个路径包含 /charts/ 的公开 apps.apple.com 榜单 URL；预填示例符合后端校验规则。
- 将 results_limit 设为 1 至 2,000，或者省略该字段并使用 backend 默认的 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}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor最佳使用场景
- 分类榜单监测： 在重复运行时保存排名、应用标识和 collected_at，形成可区分的时间点榜单快照。
- 排名应用目录补全： 为榜单中发现的条目补充应用 ID、名称、开发者、分类、商店 URL、说明和图片。
- 商店信息比较： 结合同一分类榜单返回的排名、评分、评价数和价格字段，比较不同应用的公开商店信息。
使用建议
- 请提交路径包含 /charts/ 的 apps.apple.com 榜单 URL；单个应用详情 URL 和无关路径会在采集开始前被拒绝。
- 如果每个榜单都需要独立配额，请拆分为不同任务；即使 urls 包含多个榜单，results_limit 仍限制整个任务保存的总记录数。
- next_cursor 只用于翻阅 SocQ 已保存的结果，不会请求下一页来源榜单，也不会扩大原任务的结果上限。
- 如果需要保留应用在多个重叠榜单中的每次出现，请分开运行任务，因为同一任务会按应用 ID 或来源 URL 去重。
- 处理下游展示时应允许说明、评分、评价数、价格、图片等选填字段为空，并直接省略没有值的字段。
相关 API
需要其他类型的 Apple App Store 公开数据时，可以使用以下 API。
- Apple App Store App Detail API — 通过已知 App Store 商品页 URL 获取标准化公开应用标识、介绍信息、开发者与分类上下文、可见评分、价格和媒体。
- Apple App Store App Reviews API — 通过已知 apps.apple.com URL 采集公开应用评价，返回标准化文本、评分、评价者、时间和应用关联信息。