获取 Google App 榜单结果（高级版）

接口说明

该接口用于根据任务 id 获取 Google Play 榜单抓取结果。返回应用 ID、标题、评分、评论数、价格、开发信息等。

结果会严格对应您在创建任务时提交的参数：

• app_collection
• location_code
• language_code

本接口会尽可能高精度模拟目标环境，因此返回结果通常可与任务创建时对应地区、语言下的榜单保持一致。您也可以通过响应中的 check_url 在无痕模式下自行校验结果准确性。

需要注意的是，个性化因素不会计结果，例如：

• 用户偏好
• 搜索历史
• 登录状态个性化推荐

请求方式

GET https://api.seermartech.cn/v3/app_data/google/app_list/task_get/advanced/$id

计费说明

在创建任务时扣费，任务结果在随后 30 天可反复查询。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数

字段	类型	说明
id	string	任务唯一标识，UUID 格式。创建任务后返回，可在 30 天随时用于获取结果。

沙箱调试

可通过以下沙箱地址查看该接口完整字段结构，返回值为模拟数据，不会扣费：

https://sandbox.seermartech.cn/v3/app_data/google/app_list/task_get/advanced/00000000-0000-0000-0000-000000000000

返回结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段	类型	说明
version	string	当前 API 版本。
status_code	integer	通用状态码。完整错误码请参考 /v3/appendix/errors。建议在接时实现完整异常处理。
status_message	string	通用状态信息。
time	string	接口执行耗时，单位秒。
cost	float	本次请求对应任务总成本，单位 USD。
tasks_count	integer	tasks 数组中的任务数量。
tasks_error	integer	tasks 数组中返回错误的任务数量。
tasks	array	任务结果列表。

tasks 数组字段

字段	类型	说明
id	string	任务唯一标识，UUID 格式。
status_code	integer	任务状态码，范围通常为 10000-60000。完整错误码请参考 /v3/appendix/errors。
status_message	string	任务状态信息。
time	string	任务执行耗时，单位秒。
cost	float	该任务成本，单位 USD。
result_count	integer	result 数组中的结果数量。
path	array	请求路径。
data	object	与创建任务时提交参数一致的原始任务参数。
result	array	榜单结果数组。

result 数组字段

字段	类型	说明
keyword	string	创建任务时传的应用榜单类型，即 app_collection。
se_domain	string	创建任务时使用的搜索引擎域名。
location_code	integer	创建任务时传的位置编码。
language_code	string	创建任务时传的语言编码。
check_url	string	对应结果页直达链接，可用于人工校验结果。
datetime	string	结果获取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。例如：2019-11-15 12:57:46 +00:00
se_results_count	integer	结果总数。
items_count	integer	当前返回的应用数量。若需更多结果，请在创建任务时提高 depth。
items	array	应用列表。

items 数组字段

字段	类型	说明
type	string	结果类型。固定可能值：google_play_search_organic
rank_group	integer	同类型结果中的组排名。不同 type 的结果不会计该排名。
rank_absolute	integer	榜单中的绝对排名。
position	string	结果展示位置。当前可返回：left
app_id	string	应用 ID。
title	string	应用标题。
url	string	Google Play 应用页链接。
icon	string	应用图标链接。
reviews_count	integer	评论总数。
rating	object	应用评分信息。
rating_type	string	评分类型。当前可返回：Max5
value	float	平均评分值。
votes_count	integer	反馈数量。该场景下通常为 null。
rating_max	integer	当前评分体系的最大值。Max5 对应为 5。
is_free	boolean	是否。
price	object	价格信息。
current	float	当前价格。
regular	float	常规价格。
max_value	float	最大价格值。
currency	string	价格币种，ISO 货币代码。
is_price_range	boolean	是否为价格区间。
displayed_price	string	结果页展示的原始价格文本。
developer	string	开发名称。
developer_url	string	开发 Google Play 页面链接。

认证方式

请求头统一使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY

请求示例

cURL

id="04011058-0696-0199-0000-2196151a15cb"

curl --location --request GET "https://api.seermartech.cn/v3/app_data/google/app_list/task_get/advanced/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

task_id = "06141103-2692-0309-1000-980b778b6d25"
url = f"https://api.seermartech.cn/v3/app_data/google/app_list/task_get/advanced/{task_id}"

headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json

if data.get("status_code") == 20000:
 print(data)
else:
 print(f"请求失败：{data.get('status_code')} - {data.get('status_message')}")

TypeScript

import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/app_data/google/app_list/task_get/advanced/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 输出结果数据
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

{
 "version": "0.1.20220428",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0431 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "app_list",
 "se": "google",
 "api": "app_data",
 "function": "app_list",
 "app_collection": "topselling_free",
 "location_code": 2840,
 "language_code": "en",
 "depth": 100,
 "app_category": "shopping",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {}
 ]
 }
 ]
}

错误处理建议

建议至少处理以下几类：

• 顶层 status_code 非 20000
• tasks_error 大于 0
• 单个任务 status_code 大于等于 40000
• result 为空或不存在
• 任务已过 30 天有效期，导致结果不可再查询

完整错误码与状态信息请参考：

• /v3/appendix/errors

使用说明补

• 该接口用于按任务 ID 获取结果
• 若需发现已完成任务，可合 /v3/app_data/google/app_list/tasks_ready
• 若需获取更多应用结果，请在创建任务时设置更大的 depth
• data 字段会原样回显任务创建时传的参数，便于结果归档和追踪

实用场景

• 监控榜单排名变化：定期拉取指定 app_collection 的榜单结果，跟踪自家或竞品应用排名波动，增长复盘。
• 分析竞品定价策略：结合 is_free、price、displayed_price 等字段，识别竞品/付费分布与价格区间。
• 挖掘头部开发：基于 developer 与 developer_url 聚合上榜应用，识别某分类中的强势发行方与产品矩阵。
• 评估应用口碑表现：利用 rating、reviews_count 等指标，对比不同地区或语言环境下的用户反馈表现。
• 追踪分类市场格局：围绕特定 app_category 和地区榜单，观察头部应用更替、品类集中度及门槛。