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

GET /v3/serp/wp/v2/task_get/regular/$id

通过已提交任务的唯一标识符获取 WP V2 常规 SERP 结果。任务结果自任务创建后保留 30 天，可在有效期重复获取；费用在提交任务时产生。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求

http

GET https://api.seermartech.cn/v3/serp/wp/v2/task_get/regular/{id}
Authorization: Bearer smt_live_YOUR_KEY

路径参数

参数	类型	填	说明
`id`	string	是	任务唯一标识符，采用 UUID 格式。任务提交后 30 天可用于查询结果。

本接口为 GET 请求，无需请求体。

沙箱测试

可使用以下沙箱地址查看该类结果的完整字段结构。沙箱返回模拟数据，不产生费用：

text

https://sandbox.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 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 数组字段

字段	类型	说明
`id`	string	任务唯一标识符，UUID 格式。
`status_code`	integer	任务状态码，取值范围通常为 `10000` 至 `60000`。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果数量。
`path`	array	用于获取该任务结果的 URL 路径。
`data`	object	创建任务时提交的原始参数。
`result`	array	SERP 结果数组。

`tasks.data` 字段

data 对象会返回创建任务时指定的参数，常见字段如下：

字段	类型	说明
`api`	string	API 服务类型。
`function`	string	调用功能，例如 `task_get`。
`se`	string	搜索引擎标识。
`se_type`	string	搜索类型。
`language_name`	string	语言名称。
`location_name`	string	地理位置名称。
`keyword`	string	查询。
`priority`	string	任务优级。
`tag`	string	提交任务时定义的自定义标签。
`device`	string	检索设备类型，例如 `desktop`。
`os`	string	操作系统类型，例如 `windows`。

`result` 数组字段

字段	类型	说明
`keyword`	string	提交任务时的。URL 编码字符会被解码，`+` 会转换为空格。
`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	搜索引擎自动纠错信息；未发生纠错时通常为 `null`。
`refinement_chips`	object	搜索细化标签信息；该接口中该字段恒为 `null`。
`item_types`	array	本次 SERP 中检测到的结果类型集合。
`se_results_count`	integer	搜索结果总量。
`pages_count`	integer	已获取的 SERP 页数。
`items_count`	integer	`items` 数组中返回的结果数量。
`items`	array	SERP 结果数组。

`spell` 字段

当搜索引擎对进行了自动纠错时，spell 将以下字段：

字段	类型	说明
`keyword`	string	搜索引擎纠正后的，结果基于该返回。
`type`	string	自动纠错类型。可选值：`including_results_for`。

`item_types` 支持的结果类型

item_types 会列出当前 SERP 中发现的结果类型，可能：

text

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

本常规接口返回以下类型的详细数据：

organic
paid
featured_snippet

如需获取图片、本地、搜索、视频等 SERP 功能和富媒体结果，请使用对应的 Advanced SERP 接口。

自然搜索结果

当 items 中的 type 为 organic 时，以下字段：

字段	类型	说明
`type`	string	结果类型，固定为 `organic`。
`rank_group`	integer	同类型结果组排名。不同类型不计该排名。
`rank_absolute`	integer	所有 SERP素中的绝对排名。
`page`	integer	该结果所在的搜索结果页码。
`domain`	string	结果所属域名。
`title`	string	搜索结果标题。
`description`	string	搜索结果描述摘要。
`url`	string	搜索结果链接。
`breadcrumb`	string	搜索结果面屑路径。

请求示例

curl

bash

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

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

Python

以下示例获取已完成任务列表，再逐项获取常规结果。

python

import requests

BASE_URL = "https://api.seermartech.cn"
HEADERS = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

# 1. 获取已完成任务列表
ready_response = requests.get(
    f"{BASE_URL}/v3/serp/wp/v2/tasks_ready",
    headers=HEADERS,
    timeout=30,
)
ready_data = ready_response.json()

if ready_data.get("status_code") == 20000:
    results = []

    for task_group in ready_data.get("tasks", []):
        for task_info in task_group.get("result", []):
            # 2. 使用任务返回的常规结果地址获取数据
            endpoint = task_info.get("endpoint_regular")
            if endpoint:
                result_response = requests.get(
                    f"{BASE_URL}{endpoint}",
                    headers=HEADERS,
                    timeout=30,
                )
                results.append(result_response.json())

            # 也可通过任务 ID 直接获取结果：
            # task_id = task_info.get("id")
            # result_response = requests.get(
            #     f"{BASE_URL}/v3/serp/wp/v2/task_get/regular/{task_id}",
            #     headers=HEADERS,
            #     timeout=30,
            # )

    print(results)
else:
    print(
        f"请求失败：{ready_data.get('status_code')} "
        f"{ready_data.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const taskId = "02201650-1073-0066-2000-1d132bb28897";

async function getTaskResult() {
  try {
    const response = await axios.get(
      `https://api.seermartech.cn/v3/serp/wp/v2/task_get/regular/${taskId}`,
      {
        headers: {
          Authorization: "Bearer smt_live_YOUR_KEY",
          "Content-Type": "application/json",
        },
      }
    );

    // 输出任务结果
    console.log(response.data);
  } catch (error) {
    console.error("获取任务结果失败：", error);
  }
}

getTaskResult();

响应示例

json

{
  "version": "0.1.20200129",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.3059 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "09171517-0696-0242-0000-a96bc1ad0bce",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.2314 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "wp",
        "v2",
        "task_get",
        "regular",
        "09171517-0696-0242-0000-a96bc1ad0bce"
      ],
      "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": [
        {
          "keyword": "flight ticket new york san francisco",
          "type": "v2",
          "se_domain": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://example.com/search?q=flight+ticket+new+york+san+francisco",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "spell": null,
          "refinement_chips": null,
          "item_types": [
            "organic",
            "paid"
          ],
          "se_results_count": 85600000,
          "pages_count": 1,
          "items_count": 1,
          "items": [
            {
              "type": "organic",
              "rank_group": 1,
              "rank_absolute": 1,
              "page": 1,
              "domain": "example.com",
              "title": "示例自然搜索结果标题",
              "description": "示例搜索结果描述。",
              "url": "https://example.com/flight-tickets",
              "breadcrumb": "example.com > flights"
            }
          ]
        }
      ]
    }
  ]
}

状态与错误处理

当顶层 status_code 为 20000 时，表示请求已成功处理。
即使顶层请求成功，仍应逐项检查 tasks[].status_code，以确认每个任务是否成功返回结果。
当任务状态码为 40000 或更高时，应记录 status_message 并执行重试、告警或人工排查。
若 result 为 null，通常表示任务尚未完成、任务不存在、任务已过期，或任务处理失败。
任务结果保留 30 天，期限后无法继续通过任务 ID 获取。

实用场景

批量回收已完成任务结果：定时调用 tasks_ready 并使用本接口获取结果，降低轮询未完成任务的请求量。
追踪自然排名：读取 organic 结果中的 rank_absolute、domain 和 url，评估目标站点在指定下的可见性。
监测竞品搜索覆盖度：按抓取自然结果并统计竞品域名出现频率，识别竞品重点布局的搜索主题。
核验搜索结果采集质量：使用 check_url 对搜索结果页，排查地域、语言或设备差异。
识别 SERP 页面机会：结合 item_types 判断是否存在精选摘要、付费结果或本地结果等版块，为优化和投放策略提供依据。

按任务 ID 获取 WP V2 常规 SERP 结果 ​

请求 ​

路径参数 ​

沙箱测试 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

tasks.data 字段 ​

result 数组字段 ​

spell 字段 ​

item_types 支持的结果类型 ​

自然搜索结果 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应示例 ​

状态与错误处理 ​

实用场景 ​