通过任务 ID 获取 WP V2 SERP 常规结果

接口说明

使用任务 id 获取已提交 SERP 任务的常规结果。

请求方式： GET接口地址： https://api.seermartech.cn/v3/serp/wp/v2/task_get/regular/$id

该接口对已创建的任务返回结果。任务创建时产生费用，结果查询在任务创建后的 30 天。

计费说明：

• 本接口本身不重复计费，费用在创建任务时产生
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

路径参数

字段	类型	说明
id	string	任务唯一标识，UUID 格式。任务结果可在任务创建后 30 天 随时查询。

沙盒调试

可通过以下沙盒地址获取带有模拟数据的完整响应结构，用于联调与字段验证：

https://api.seermartech.cn/v3/serp/yahoo/organic/task_get/regular/00000000-0000-0000-0000-000000000000

说明：

• 沙盒返回当前端点可用的字段
• 字段为模拟值
• 使用沙盒接口不会产生费用

响应结构

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

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表见参考文档中的错误码说明
status_message	string	通用状态信息
time	string	执行耗时，单位秒
cost	float	本次请求总成本，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务结果数组

tasks[] 字段

字段	类型	说明
id	string	任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态说明
time	string	任务执行耗时，单位秒
cost	float	任务成本，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	与创建任务时 POST 请求中传的参数一致
result	array	实结果数组

result[] 字段

字段	类型	说明
keyword	string	创建任务时传的；返回时会对 %## 做解码，+ 会被解码为空格
type	string	创建任务时指定的搜索引擎类型
se_domain	string	创建任务时指定的搜索引擎域名
location_code	integer	创建任务时指定的位置代码
language_code	string	创建任务时指定的语言代码
check_url	string	对应搜索结果页的直达链接，可用于人工校验结果准确性
datetime	string	结果获取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
spell	object	搜索引擎自动纠错信息；如搜索引擎对进行了纠错，将返回纠错后的及纠错类型
refinement_chips	object	搜索细化标签，固定为 null
item_types	array	当前 SERP 中检测到的结果类型列表
se_results_count	integer	SERP 结果总数
pages_count	integer	已抓取的结果页数
items_count	integer	items 数组中的结果数量
items	array	当前 SERP 中的结果项

spell 对象

字段	类型	说明
keyword	string	搜索引擎纠错后的
type	string	纠错类型，可选值：including_results_for

item_types 可选值

featured_snippet, images, local_pack, hotels_pack, organic, paid, people_also_ask, related_searches, shopping, recipes, top_stories, video, ai_overview

说明：

• item_types 会列出 SERP 中检测到的结果类型
• 但本接口返回 organic、paid、featured_snippet 类型的数据
• 若需获取页面中 SERP 功能结果与富结果，建议改用对应的 Advanced SERP 接口

items[] 字段说明

organic 类型结果

字段	类型	说明
type	string	结果类型，固定为 organic
rank_group	integer	同类型结果组排名在相同 type 的结果中排序
rank_absolute	integer	SERP局绝对排名
page	integer	结果所在页码
domain	string	结果域名
title	string	标题
description	string	摘要描述
url	string	结果落地页 URL
breadcrumb	string	面屑路径

调用示例

cURL

id="09171517-0696-0242-0000-a96bc1ad0bce"

curl --location --request GET "https://api.seermartech.cn/v3/serp/wp/v2/task_get/regular/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

task_id = "09171517-0696-0242-0000-a96bc1ad0bce"
url = f"https://api.seermartech.cn/v3/serp/wp/v2/task_get/regular/{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 = "02201650-1073-0066-2000-1d132bb28897";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/wp/v2/task_get/regular/${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.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3059 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "wp",
 "se_type": "v2",
 "language_name": "English",
 "location_name": "United States",
 "keyword": "flight ticket new york san francisco",
 "priority": "2",
 "tag": "tag2",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 85600000,
 "pages_count": 1,
 "items_count": 96,
 "items": []
 }
 ]
 }
 ]
}

状态码与异常处理

建议对以下两层状态进行处理：

1. 顶层状态：status_code、status_message
2. 任务级状态：tasks[].status_code、tasks[].status_message

处理建议：

• 当顶层 status_code 非成功值时，直接按请求失败处理
• 当顶层成功但 tasks[].status_code 为错误码时，按单任务失败处理
• 当 result 为空时，应视为任务未完成、结果不存在或任务异常
• 建议在系统中实现统一的重试、告警与异常日志记录机制

使用建议

• 通过任务提交接口创建任务，再保存返回的 id
• 若需要批量轮询已完成任务，可结合 /v3/serp/wp/v2/tasks_ready
• 获取结果后可使用 check_url 对搜索引擎页面进行抽样核验
• 如需更丰富的 SERP 特征数据，应使用对应的高级结果接口

实用场景

• 查询排名结果：按任务 ID 拉取指定的 SERP 数据，快速验证目标页面在自然结果中的位置。
• 监控竞品落地页：提取 domain、title、url 等字段，追踪竞品在目标下的展示。
• 校验搜索抓取准确性：利用 check_url 回看真实搜索页，对比接口返回，提升数据质检效率。
• 分析自然结果分布：基于 rank_absolute、page、items_count 等字段，评估结果页结构与竞争密度。
• 识别自动纠错：通过 spell 字段判断搜索引擎是否改写了原始查询词，误判排名与搜索意图。