百度 SERP 任务创建

GET /v3/appendix/errors

POST /v3/serp/wp/v2/task_post

本接口用于创建百度自然搜索结果页（SERP）采集任务，默认返回前 10 条搜索结果。结果会基于指定的地理位置、语言、设备和操作系统生成。

任务支持两种执行优级：

1：普通优级，默认值。
2：高优级，通常可更快完成，但会产生额外费用。

任务创建成功后，可使用响应中的唯一任务 ID 获取结果；也可以通过 postback_url 或 pingback_url 接收任务完成通知。

平台限流以认证说明中的 30/60/120 次/分钟规则为准。单次 100 个任务的部分将返回 40006 错误。 > > 任务在创建时计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。 > > depth 每增加至 10 条结果，若搜索引擎返回更多结果，可能产生额外费用。启用 get_website_url: true 时，单个任务费用将增至原来的 10 倍。

请求地址

text

POST https://api.seermartech.cn/v3/serp/wp/v2/task_post

请求头

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求体

请求体是 UTF-8 编码的 JSON 数组，每个数组代表一个创建的任务。

json

[
  {
    "keyword": "iPhone 12",
    "location_code": 2156,
    "language_code": "zh_CN",
    "device": "desktop",
    "depth": 10
  }
]

请求参数

参数	类型	填	说明
`keyword`	string	是	查询，最长 700 个字符。`+` 会被解码为空格；如需要 `%`，请使用 `%25`；如需 `+`，请使用 `%2B`。
`priority`	integer	否	任务优级。`1`：普通优级，默认；`2`：高优级，高优级任务会额外计费。
`depth`	integer	否	需要解析的 SERP 结果数量。默认值：`10`；最大值：`700`。每 10 条结果通常对应一个 SERP 计费单位。
`max_crawl_pages`	integer	否	最大抓取结果页数。默认值：`1`；最大值：`100`。该参数与 `depth`合使用。
`language_name`	string	条件填	搜索语言称。未提供 `language_code` 时填。百度支持的语言为 `Chinese (Simplified)`。可通过 `GET /v3/serp/wp/languages` 获取可用语言列表。
`language_code`	string	条件填	搜索语言代码。未提供 `language_name` 时填。百度简体中文代码为 `zh_CN`。可通过 `GET /v3/serp/wp/languages` 获取可用语言列表。
`location_name`	string	条件填	搜索地理位置称。未提供 `location_code` 和 `location_coordinate` 时填。使用该字段时无需同时传另外两种位置参数。示例：`New York,New York,United States`。
`location_code`	integer	条件填	搜索地理位置代码。未提供 `location_name` 和 `location_coordinate` 时填。使用该字段时无需同时传另外两种位置参数。示例：`2156`。可通过 `GET /v3/serp/wp/locations` 获取位置列表。
`location_coordinate`	string	条件填	GPS 坐标，格式为 `latitude,longitude,radius`。未提供 `location_name` 和 `location_code` 时填。纬度和经度最多保留 7 位小数；半径范围为 `199.9` 至 `199999` 毫米。系统将匹坐标附近城市，结果不一定精确对应指定坐标，不建议作为常规定位方式。示例：`53.476225,-2.243572,200`。
`device`	string	否	设备类型：`desktop`、`mobile` 或 `tablet`。默认值：`desktop`。
`os`	string	否	设备操作系统。`desktop` 可选 `windows`、`macos`，默认 `windows`；`mobile` 和 `tablet` 可选 `android`、`ios`，默认 `android`。
`get_website_url`	boolean	否	是否返回排名结果的真实落地 URL。默认值：`false`。百度结果链接通常是搜索引擎编码后的跳转地址；设置为 `true` 后，本平台会额外请求每个结果以解析真实 URL，因此任务费用将乘以 10。
`stop_crawl_on_match`	array	否	停止抓取条件数组，最多可 10 个目标对象。达到指定匹条件后，将返回截至该目标所在位置的 SERP 结果。系统会对达到条件前抓取的每个 SERP 计费。
`stop_crawl_on_match[].match_value`	string	条件填	匹目标值。当传 `stop_crawl_on_match` 时填。可指定域名、子域名或通符规则；域名不得 `http://` 或 `https://` 协议。示例：`example.com`、`/blog/post-*`。
`stop_crawl_on_match[].match_type`	string	条件填	匹方式。当传 `stop_crawl_on_match` 时填。可选值：`domain`（指定域名或子域名）、`with_subdomains`（主域名及子域名）、`wildcard`（通符规则）。
`tag`	string	否	自定义任务标识，最长 255 个字符。可用于将任务与业务记录；该值会在响应的 `data` 对象中原样返回。
`postback_url`	string	否	任务完成后的结果回调地址。本平台将向该地址发送 `POST` 请求，并以 gzip 格式压缩结果数据。支持 `$id` 和 `$tag` 占位符，发送时会替换为任务 ID 和 URL 编码后的标签。特殊字符会进行 URL 编码，例如 `#` 会编码为 `%23`。
`postback_data`	string	条件填	指定 `postback_url` 时填。定义回调数据类型，可选：`regular`、`html`。
`pingback_url`	string	否	任务完成通知地址。本平台将向该地址发送 `GET` 请求。支持 `$id` 和 `$tag` 占位符，发送时会替换为值。特殊字符会进行 URL 编码。

`stop_crawl_on_match` 示例

json

[
  {
    "keyword": "SEO 工",
    "location_code": 2156,
    "language_code": "zh_CN",
    "depth": 50,
    "stop_crawl_on_match": [
      {
        "match_type": "with_subdomains",
        "match_value": "example.com"
      }
    ]
  }
]

回调说明

Postback 回调

postback_url 后，任务完成时本平台会向指定地址发送完整结果的 POST 请求。请求数据使用 gzip 压缩。

text

https://your-server.com/postback?id=$id&tag=$tag

使用 postback_url 时，同时指定 postback_data：

json

[
  {
    "keyword": "iPhone 12",
    "location_code": 2156,
    "language_code": "zh_CN",
    "postback_url": "https://your-server.com/postback?id=$id&tag=$tag",
    "postback_data": "regular"
  }
]

Pingback 回调

pingback_url 后，任务完成时本平台会向指定地址发起 GET 请求用于通知任务已完成。收到通知后，您可以使用任务 ID 查询任务结果。

text

https://your-server.com/ping?id=$id&tag=$tag

> 回调服务应在 10 秒返回响应。若回调时或连接失败，任务将转已完成任务列表，您可后续通过任务 ID 拉取结果。

curl 示例

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/wp/v2/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keyword": "iPhone 12",
      "location_code": 2156,
      "language_code": "zh_CN",
      "device": "desktop",
      "os": "windows",
      "depth": 10,
      "tag": "baidu-iphone-ranking"
    }
  ]'

Python 示例

python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/task_post"

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

# 请求体为 JSON 数组，每个表示一个任务
payload = [
    {
        "keyword": "iPhone 12",
        "location_code": 2156,
        "language_code": "zh_CN",
        "device": "desktop",
        "os": "windows",
        "depth": 10,
        "tag": "baidu-iphone-ranking",
        "pingback_url": "https://your-server.com/ping?id=$id&tag=$tag",
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()

result = response.json()

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

TypeScript 示例

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/serp/wp/v2/task_post",
  [
    {
      keyword: "iPhone 12",
      location_code: 2156,
      language_code: "zh_CN",
      device: "desktop",
      os: "windows",
      depth: 10,
      priority: 2,
      tag: "baidu-iphone-ranking",
      pingback_url: "https://your-server.com/ping?id=$id&tag=$tag",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

if (response.data.status_code === 20000) {
  console.log(response.data);
} else {
  console.error(
    `请求失败：${response.data.status_code} - ${response.data.status_message}`
  );
}

响应字段

接口返回 JSON 对象 tasks 数组各任务的创建状态和任务标识。

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求整体状态码。建议根据状态码实现异常和错误处理逻辑。错误码参考 `GET /v3/appendix/errors`。
`status_message`	string	请求整体状态说明。
`time`	string	请求处理耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	创建失败的任务数量。
`tasks`	array	任务结果数组。
`tasks[].id`	string	本平台生成的唯一任务 ID，采用 UUID 格式。用于后续获取任务结果或回调通知。
`tasks[].status_code`	integer	单个任务状态码，取值范围通常为 `10000` 至 `60000`。
`tasks[].status_message`	string	单个任务状态说明。
`tasks[].time`	string	单个任务处理耗时，单位为秒。
`tasks[].cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks[].result_count`	integer	`result` 数组中的数量。创建任务成功时通常为 `0`。
`tasks[].path`	array	请求接口路径信息。
`tasks[].data`	object	创建任务时提交的参数，以及系统补的默认参数。
`tasks[].result`	array / null	任务创建接口不直接返回 SERP 结果，通常为 `null`。任务完成后请通过任务 ID 获取结果，或使用回调接收结果。

响应示例

json

{
  "version": "0.1.20201026",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1573 sec.",
  "cost": 0.00225,
  "tasks_count": 2,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "10301446-1535-0066-0000-182aa9de58c6",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0089 sec.",
      "cost": 0.0015,
      "result_count": 0,
      "path": [
        "v3",
        "serp",
        "wp",
        "v2",
        "task_post"
      ],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "baidu",
        "se_type": "organic",
        "location_code": 2156,
        "language_code": "zh_CN",
        "keyword": "iPhone 12",
        "tag": "baidu-iphone-ranking",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    },
    {
      "id": "10301446-1535-0066-0000-182aa9de58c7",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0091 sec.",
      "cost": 0.00075,
      "result_count": 0,
      "path": [
        "v3",
        "serp",
        "wp",
        "v2",
        "task_post"
      ],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "baidu",
        "se_type": "organic",
        "location_name": "China",
        "language_code": "zh_CN",
        "keyword": "最佳 iPhone",
        "priority": 2,
        "tag": "baidu-iphone-ranking-priority",
        "pingback_url": "https://your-server.com/ping?id=$id&tag=$tag",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

实用场景

监控品牌词排名：按日创建品牌词和产品词任务，追踪百度自然搜索变化，及时发现负面或竞品页面抢占排名。
对比多地域搜索结果：针对不同 location_code 提交同一，识别区域化排名差异，为本地化投放和区域市场运营提供依据。
分析移动端与桌面端可见性：分别设置 device 为 mobile 和 desktop，定位不同设备上的排名波动与页面适问题。
追踪竞品首次出现位置：通过 stop_crawl_on_match 监测指定竞品域名，确定竞品搜索结果的位置并控制不的深度抓取。
获取真实落地页地址：启用 get_website_url 解析百度跳转链接，建立、排名 URL 与目标页面之间的准确映射，用于落地页审计和归因。

百度 SERP 任务创建 ​

请求地址 ​

请求头 ​

请求体 ​

请求参数 ​

stop_crawl_on_match 示例 ​

回调说明 ​

Postback 回调 ​

Pingback 回调 ​

curl 示例 ​

Python 示例 ​

TypeScript 示例 ​

响应字段 ​

响应示例 ​

实用场景 ​

百度 SERP 任务创建

请求地址

请求头

请求体

请求参数

`stop_crawl_on_match` 示例

回调说明

Postback 回调

Pingback 回调

curl 示例

Python 示例

TypeScript 示例

响应字段

响应示例

实用场景