获取 SERP 已完成的重新解析任务

GET /v3/serp/google/organic/tasks_fixed

本接口使用 GET 方法，路径为：

GET https://api.seermartech.cn/v3/serp/$path/tasks_fixed

接口说明

“Tasks Fixed”接口用于获取已完成重新解析、但尚未被收集的 SERP 任务列表。

当您使用 Standard 方法提交任务且未设置 postback_url 时，可通过本接口获取所有已完成重新解析任务的 id，然后使用对应的“Task GET”接口重新获取修复后的结果。

本接口返回最近 24 小时完成且尚未被收集的任务。

计费说明

接收本接口返回的结果不产生费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制

每个任务会一直保留在列表中，直到被成功收集。
每分钟最多调用 20 次。
每次调用最多返回最近 24 小时完成的 1000 个任务。
已经被收集的任务不会再次出现在列表中。
完成后 24 小时仍未收集的任务不会出现在列表中。

如果提交任务时设置了 postback_url，任务默认不会出现在本接口返回的列表中。只有当本平台向您的服务器发送回调失败，且您的服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在收集列表中。

请求地址

text

GET /v3/serp/{path}/tasks_fixed

，{path} 用于指定搜索引擎和搜索类型。

`path` 可选值

`path`	说明
`google/organic`	Google 自然搜索
`google/maps`	Google 地图
`google/news`	Google 新闻
`google/events`	Google 活动
`google/images`	Google 图片
`google/search_by_image`	Google 以图搜图
`google/jobs`	Google 招聘
`google/local_finder`	Google 本地搜索
`google/dataset_search`	Google 数据集搜索
`google/dataset_info`	Google 数据集
`google/autocomplete`	Google 自动补
`google/ai_mode`	Google AI 模式
`bing/organic`	Bing 自然搜索
`yahoo/organic`	Yahoo 自然搜索
`baidu/organic`	百度自然搜索
`naver/organic`	Naver 自然搜索
`seznam/organic`	Seznam 自然搜索
`youtube/organic`	YouTube 自然搜索
`youtube/video_info`	YouTube 视频信息
`youtube/video_subtitles`	YouTube 视频字幕
`youtube/video_comments`	YouTube 视频评论

请求头

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

本接口为 GET 请求，不需要请求体。

curl 示例

bash

curl --location --request GET \
  "https://api.seermartech.cn/v3/serp/google/organic/tasks_fixed" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

您可以将 URL 中的 google/organic 替换为支持的 path。

Python 示例

python

import requests

url = "https://api.seermartech.cn/v3/serp/google/organic/tasks_fixed"

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(
        "请求失败。错误码：%s，错误信息：%s"
        % (data.get("status_code"), data.get("status_message"))
    )

TypeScript 示例

typescript

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/serp/google/organic/tasks_fixed",
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
      // 在此处理已完成重新解析的任务
    } else {
      console.error(
        `请求失败。错误码：${result.status_code}，错误信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络请求失败：", error.message);
  });

返回结构

接口返回 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	请求 URL 中传的参数
`result`	array	已完成重新解析任务的结果列表

`result` 中的字段

字段	类型	说明
`id`	string	已完成任务的唯一标识，采用 UUID 格式
`se`	string	创建任务时指定的搜索引擎
`se_type`	string	搜索引擎类型，当前可返回 `v2`
`date_fixed`	string	任务完成修复的时间，使用 UTC 格式
`tag`	string	用户自定义任务标识
`endpoint_regular`	string / null	SERP Regular 任务结果收集地址。如果对应端点不支持 SERP Regular，则返回 `null`
`endpoint_advanced`	string / null	SERP Advanced 任务结果收集地址。如果对应端点不支持 SERP Advanced，则返回 `null`
`endpoint_html`	string / null	SERP HTML 任务结果收集地址。如果对应端点不支持 SERP HTML，则返回 `null`

> 建议在业务系统中完善状态码、空列表、任务收集失败和重复收集等异常的处理逻辑。

返回示例

json

{
  "version": "0.1.20200129",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2270 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "/v3/serp/google/organic/tasks_fixed"
      ],
      "data": {
        "api": "serp",
        "function": "tasks_fixed",
        "se": "google",
        "se_type": "organic"
      },
      "result": [
        {
          "id": "00000000-0000-0000-0000-000000000002",
          "se": "google",
          "se_type": "organic",
          "date_fixed": "2024-01-29 12:00:00 +00:00",
          "tag": "example-task",
          "endpoint_regular": "/v3/serp/google/organic/task_get/regular",
          "endpoint_advanced": "/v3/serp/google/organic/task_get/advanced",
          "endpoint_html": "/v3/serp/google/organic/task_get/html"
        }
      ]
    }
  ]
}

实用场景

轮询收集任务：定期获取尚未收集的重新解析任务 ID，因临时回调失败而遗漏修复后的 SERP 数据。
重新获取修复结果：根据 endpoint_regular、endpoint_advanced 或 endpoint_html 收集更新后的 SERP 结果，提升排名数据准确性。
补偿回调失败任务：监控 postback_url 回调失败的任务，并通过任务收集接口执行自动补偿。
构建任务理机制：结合 date_fixed 和任务收集状态，理已处理任务并降低重复请求。
校验不同 SERP 格式：根据各结果收集端点是否为 null，判断任务支持的结果格式并选择对应的数据处理流程。

获取 SERP 已完成的重新解析任务 ​

接口说明 ​

计费说明 ​

调用限制 ​

请求地址 ​

path 可选值 ​

请求头 ​

curl 示例 ​

Python 示例 ​

TypeScript 示例 ​

返回结构 ​

顶层字段 ​

tasks 中的任务字段 ​

result 中的字段 ​

返回示例 ​

实用场景 ​