获取 Google App List HTML 结果

接口说明

用于根据任务 id 获取 Google App List 任务的 HTML 抓取结果。

请求方式： GET请求地址： https://api.seermartech.cn/v3/app_data/google/app_list/task_get/html/$id

该接口适用于已提交并完成的任务结果查询。任务创建成功后在创建任务时计费；在 7 天 可多次获取该任务结果。

参考价说明：本接口结果查询本身通常不额外计费，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

---

请求参数

路径参数

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

---

返回结果

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

顶层字段

字段	类型	说明
version	string	当前 API 版本号
status_code	integer	通用状态码，完整列表见 /v3/appendix/errors
status_message	string	通用状态信息，完整列表见 /v3/appendix/errors
time	string	请求执行耗时，单位秒
cost	float	本次请求总成本，扣费以该字段为准
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	当前任务成本
result_count	integer	result 数组中的结果数量
path	array	请求路径
data	object	与创建任务时 POST 请求中一致的参数
result	array	结果数组

tasks[].result[] 字段

字段	类型	说明
keyword	string	创建任务时传的应用榜单集合
type	string	创建任务时使用的搜索引擎类型
se_domain	string	创建任务时使用的搜索引擎域名
location_code	integer	创建任务时使用的地区编码
language_code	string	创建任务时使用的语言编码
datetime	string	获取结果时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
items_count	integer	items 数组中的结果数量
items	array	HTML 页面及数据

tasks[].result[].items[] 字段

字段	类型	说明
page	integer	返回的 HTML 页序号
date	string	HTML 页面抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
html	string	页面 HTML 原文

---

使用说明

通常推荐以下两种方式获取结果：

1. 调用 /v3/app_data/google/app_list/tasks_ready 获取已完成任务列表；
2. 再使用返回的结果地址，或直接用任务 id 调用本接口获取 HTML 结果。

---

请求示例

cURL

id="04171455-0696-0192-0000-4c69cc29b945"

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

Python

import requests

task_id = "02201115-0001-0066-0000-c06c8f23fce5"
url = f"https://api.seermartech.cn/v3/app_data/google/app_list/task_get/html/{task_id}"

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

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

TypeScript

import axios from "axios";

const taskId = "02201115-0001-0066-0000-c06c8f23fce5";

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

---

获取已完成任务后再获取结果

Python 示例

import requests

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

# 1. 获取已完成任务列表
ready_url = "https://api.seermartech.cn/v3/app_data/google/app_list/tasks_ready"
ready_response = requests.get(ready_url, headers=headers).json

results = []

if ready_response.get("status_code") == 20000:
 for task_group in ready_response.get("tasks", []):
 for task_info in task_group.get("result", []) or []:
 # 2. 通过 endpoint_html 拉取 HTML 结果
 endpoint_html = task_info.get("endpoint_html")
 if endpoint_html:
 full_url = f"https://api.seermartech.cn{endpoint_html}"
 task_result = requests.get(full_url, headers=headers).json
 results.append(task_result)

 # 3. 或直接通过任务 id 获取结果
 # task_id = task_info.get("id")
 # if task_id:
 # task_result = requests.get(
 # f"https://api.seermartech.cn/v3/app_data/google/app_list/task_get/html/{task_id}",
 # headers=headers
 # ).json
 # results.append(task_result)

print(results)

TypeScript 示例

import axios from "axios";

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

async function getCompletedTaskResults {
 const tasksReady = await axios.get(
 "https://api.seermartech.cn/v3/app_data/google/app_list/tasks_ready",
 { headers }
 );

 const tasksResponses: any[] = [];

 if (tasksReady.data.status_code === 20000) {
 for (const task of tasksReady.data.tasks || []) {
 for (const item of task.result || []) {
 if (item.endpoint_html) {
 const taskResult = await axios.get(
 `https://api.seermartech.cn${item.endpoint_html}`,
 { headers }
 );
 tasksResponses.push(taskResult.data);
 }

 // 另一种方式：直接通过任务 id 获取结果
 // if (item.id) {
 // const taskResult = await axios.get(
 // `https://api.seermartech.cn/v3/app_data/google/app_list/task_get/html/${item.id}`,
 // { headers }
 // );
 // tasksResponses.push(taskResult.data);
 // }
 }
 }
 } else {
 console.error(
 `error. Code: ${tasksReady.data.status_code} Message: ${tasksReady.data.status_message}`
 );
 }

 console.log(tasksResponses);
}

getCompletedTaskResults.catch(console.error);

---

响应示例

{
 "version": "0.1.20220422",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1072 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "04171455-0696-0192-0000-4c69cc29b945",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0312 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "app_data",
 "google",
 "app_list",
 "task_get",
 "html",
 "04171455-0696-0192-0000-4c69cc29b945"
 ],
 "data": {
 "se_type": "app_list",
 "se": "google",
 "api": "app_data",
 "function": "app_list",
 "app_collection": "top_free",
 "location_code": 2840,
 "language_code": "en",
 "depth": 50,
 "app_category": "shopping",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "keyword": "top_free",
 "type": "app_list",
 "se_domain": "google.com",
 "location_code": 2840,
 "language_code": "en",
 "datetime": "2019-11-15 12:57:46 +00:00",
 "items_count": 1,
 "items": [
 {
 "page": 1,
 "date": "2019-11-15 12:57:46 +00:00",
 "html": "<!doctype html>...</html>"
 }
 ]
 }
 ]
 }
 ]
}

---

状态码与错误处理

• 顶层 status_code 表示整次请求的处理状态；
• tasks[].status_code 表示单个任务的处理状态；
• 当 tasks[].status_code 大于等于 40000，或 result 为空时，建议按异常任务处理；
• 完整错误码与信息说明请参考 /v3/appendix/errors。

建议：

• 为任务结果轮询建立容错机制；
• 对 7 天结果有效期做缓存或归档；
• 在批量获取结果时记录失败任务 id，便于补拉和重试。

实用场景

• 抓取榜单原始页面：获取应用榜单 HTML 原文，用于保留页面证据，便于后续审计、复盘与人工核验。
• 解析榜单结构变化：监控 Google App List 页面 HTML 结构变动，及时调整解析器，降低采集失败风险。
• 复盘历史榜单快：按任务 id 回查 7 天的榜单 HTML，支持排名异常、竞品波动等问题定位。
• 提取扩展字段：从 HTML 中补解析接口标准字段之外的展示，如页面模块、文案片段或特殊标签。
• 构建页面归档库：将不同地区、语言、分类的榜单 HTML 存档，支持 SEO/ASO 研究、竞品分析和趋势建模。