google-play/
app-rankings

通过已知 Google Play 榜单 URL 采集公开分类排名,并返回包含名次、应用身份、商店元数据、媒体和采集上下文的标准化记录。

Google Play App Rankings API

分类榜单 URL
标准化应用记录
按结果计费
每条结果 0.15 积分
等待提交
等待提交

填写参数并发送请求,任务状态和标准化结果会显示在这里。

README

由 SocQ 维护 · 更新于

Google Play App Rankings

提交的 Google Play 榜单 URL 决定要采集的分类或排名页面,results_limit 则把发现数量控制在 1 到 2000 条。每条已存储结果都遵循 AppItem 契约,可将 rank 与可用包名、开发者、分类、评分、评价数量、安装量、价格、媒体、来源 URL 和采集时间一同处理。

Google Play App Rankings API 主要特性

  • 批量榜单 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 App Rankings API 参数

参数必填描述
urls必填必填且非空的 Google Play 榜单 URL 数组。每个 URL 必须使用 play.google.com 或其子域,且路径包含 /store/apps/collection/ 或 /store/apps/category/;运行时不接受 country 或 category 作为独立字段。
results_limit可选可选正整数,范围为 1 到 2000,默认值为 100。它限制整个任务的发现与落库总数,并用于初始计费估算;多个 URL 会按顺序使用任务剩余额度。

如何使用 Google Play App Rankings API

提交一个或多个已知 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 继续读取

Google Play App Rankings API 最佳使用场景

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

Google Play App Rankings API 使用建议

  • 提交公开 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 积分结算,多余的预扣估算会退回。

除了 Google Play App Rankings API,需要其他类型的 Google Play 公开数据时,可以使用以下 API。

  • Google Play App Detail API — 根据已知应用链接获取标准化的 Google Play 公开商店详情,包括应用标识、商店文案、开发者、分类、可见指标、价格、媒体与采集上下文。
  • Google Play App Reviews API — 通过 play.google.com URL 采集公开应用评价,可选传入 country 上下文,并返回标准化文本、评价者、评分、时间和应用引用字段。

探索其他平台

还可以将 Google Play 数据与其他已支持社交平台的公开数据结合使用。

Google Play App Rankings API — 常见问题

Google Play App Rankings API 是一个用于通过公开 Google Play 分类榜单 URL 采集排名的 API,可返回包含可用名次、应用身份、商店元数据、媒体、来源和采集时间的标准化 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、平台、资源、类型、URL、时间、app_id、名称、正文、开发者、分类、评分、reviews_count、安装量、价格、rank 和媒体字段;来源没有提供的选填值保留为 null。

每条已存储结果消耗 0.15 个 SocQ 积分,基础费用为零。SocQ 会按 results_limit 或默认 100 条预扣,再按实际结果数量结算并退回未使用估算;空结果最终为零积分。