Google Play App Rankings API

Google Play App Rankings

主要特性

• 批量榜单 URL 输入通过非空 urls 数组提交公开 play.google.com 分类或排名页面，不需要也不接受独立 country 或 category 字段。
• Google Play 榜单 URL 校验运行时仅接受 play.google.com 及其子域，并要求路径包含 /store/apps/collection/ 或 /store/apps/category/。
• 可控采集数量results_limit 可设为 1 到 2000；省略时使用 100，这也是默认发现数量和初始计费估算。
• 统一应用排名结构通过同一种 AppItem 结构读取 rank，以及可用 app_id、名称、开发者、分类、评分、reviews_count、安装量、价格和媒体。
• 异步数据集任务提交的 URL 行会触发异步数据集采集，SocQ 将结果标准化并落库，再由共享任务读取接口返回状态。
• 落库结果 cursor任务成功后，可用读取接口返回的不透明 next_cursor 和 1 到 500 的 limit 分页；它不是 Google Play 或数据提供方的翻页标记。
• 按实际结果结算提交时按请求数量或默认数量预扣，完成后按每条已存储结果 0.15 积分结算并退回未使用估算；空结果按零积分基础费用结算。

参数

如何使用

提交一个或多个已知 Google Play 榜单 URL，跟踪异步任务，并在成功后读取标准化排名记录。

1. 选择公开 play.google.com 分类或榜单 URL，并确认所需市场和分类上下文已经包含在 URL 中。
2. 将 urls 和可选 results_limit POST 到 /v1/google-play/app-rankings，然后保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到 status 为 succeeded 或 failed；排队和运行期间不能读取结果。
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}'

# 轮询 GET /v1/tasks/{task_id}
# 使用 GET /v1/tasks/{task_id}?cursor={next_cursor}&limit=50 继续读取

最佳使用场景

• 分类榜单快照： 将 rank 与 collected_at 一同保存，对同一个 Google Play 榜单的多次独立采集进行比较。
• 排名应用发现： 把选定分类 URL 转换为标准化应用记录，用于审核、打标或补全下游应用目录。
• 应用组合位置核对： 优先使用 app_id 和开发者字段匹配内部应用组合，再检查每条返回名次，减少仅凭显示名称关联的歧义。
• 多次采集数据分析： 将固定 AppItem 字段写入数据仓库，使可空评分、评价数量、安装量、价格和排名能够跨批次处理。

使用建议

• 提交公开 Google Play 分类或榜单 URL，不要提交应用详情页、搜索词、国家代码或分类名称；请求体只包含 urls 和 results_limit。
• 请使用路径包含 /store/apps/collection/ 或 /store/apps/category/ 的 play.google.com URL；应用详情页和无关路径会在采集开始前被拒绝。
• 存在多个输入 URL 时，results_limit 由整个任务共享。URL 会按顺序处理，每个 URL 只能使用任务剩余额度；每个榜单需要独立配额时应拆分任务。
• 将应用元数据视为可空；优先保留可用 app_id、url、rank 和 collected_at，不要假设评分、评价数量、安装量、价格或媒体一定存在。
• 不要发送来源 cursor；应先等待任务成功，再仅使用 data.results 中返回的不透明 next_cursor 翻阅 SocQ 已存储记录。
• 提交时按 results_limit 预留积分，最终按每条实际落库结果 0.15 积分结算，多余的预扣估算会退回。

相关 API