提交百度自然搜索任务

接口说明

该接口用于创建百度自然搜索（SERP）抓取任务。默认返回前 10 条搜索结果，结果会受所选地区、语言、设备等参数影响。

接口支持两种任务优级：

• 1：普通优级（默认）
• 2：高优级（执行更快，费用更高）

请求地址

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

说明：本文档标题对应百度自然搜索任务，但平台容路径中同时出现了 wp/v2 与 baidu/organic 两种写法。对接时请以业务接分的容路径为准；本文保留原始容路径。

计费说明

在创建任务时扣费。

• 参考价约 ¥0.0360 / 次
• 高优级任务会额外收费
• 当 depth > 10 且搜索引擎返回 10 条结果时，可能产生附加费用
• 若开启 get_website_url=true，由于系统会为每条结果额外请求真实落地页，单任务费用将放大 10 倍
• 使用 stop_crawl_on_match 时，会按抓取到满足停止条件前的 SERP 页数计费
• 扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求规则

• 请求方法：POST
• 请求体格式：application/json
• 编码：UTF-8
• 请求体为 JSON 数组：[{ ... }]
• 单次 POST 最多可 100 个任务
• 每分钟最多可发起 2000 次 API 调用
• 如果单次 POST 中任务数 100，出部分将返回错误码 40006

任务创建后，你可以：

• 使用返回的任务 id 轮询获取结果
• 提交 postback_url，在任务完成后由平台主动 POST 返回结果
• 提交 pingback_url，在任务完成后由平台主动 GET 通知

如果你的回调服务器 10 秒未响应，连接会因时中断，任务会转对应的 Tasks Ready 列表，后续可通过任务查询接口获取结果。错误信息取决于你的服务端。

---

请求参数

顶层任务对象字段

字段名	类型	填	说明
keyword	string	是	搜索，最长 700 个字符。%## 会被解码，+ 会被解码为空格；若本身需要 %，请写为 %25；若需要 +，请写为 %2B。
priority	integer	否	任务优级。可选：1 普通优级（默认），2 高优级。高优级会产生更高费用。
depth	integer	否	抓取深度，即期望返回的搜索结果数量。默认 10，最大 700。每最多 10 条结果通常计为一个 SERP 单； 10 条可能产生额外扣费。
max_crawl_pages	integer	否	最大抓取页数。默认 1，最大 100。该参数与 depth合使用，用于限制翻页抓取范围。
language_name	string	条件填	搜索语言名称；当未传 language_code 时填。可通过 /v3/serp/wp/languages 获取可用语言。百度支持 Chinese (Simplified)。
language_code	string	条件填	搜索语言代码；当未传 language_name 时填。可通过 /v3/serp/wp/languages 获取可用语言。百度对应代码为 zh_CN。
location_name	string	条件填	地区名称；当未传 location_code 或 location_coordinate 时填。传该字段后无需再传 location_code 或 location_coordinate。示例：New York,New York,United States
location_code	integer	条件填	地区编码；当未传 location_name 或 location_coordinate 时填。传该字段后无需再传 location_name 或 location_coordinate。示例：2156
location_coordinate	string	条件填	坐标定位；当未传 location_name 或 location_code 时填。格式：latitude,longitude,radius。 latitude 与 longitude 最多 7 位小数，radius 最小 199.9、最大 199999（毫米）。系统会按最近城市返回结果，因此不建议使用该参数做高精度定位。示例：53.476225,-2.243572,200
device	string	否	设备类型。可选：desktop、mobile、tablet。默认 desktop。
os	string	否	设备操作系统。若 device=desktop，可选 windows、macos，默认 windows；若 device=mobile 或 tablet，可选 android、ios，默认 android。
get_website_url	boolean	否	是否返回每个排名结果的真实直达链接。默认 false。百度原始结果链接通常是编码跳转链接；若设为 true，平台会额外解析真实 URL，但任务费用会变为原来的 10 倍。
stop_crawl_on_match	array	否	命中指定目标后停止继续翻页抓取。最多可传 10 个目标对象。若该参数，结果会返回到目标命中的那一条为止。
tag	string	否	自定义任务标识，最长 255 个字符。可用于结果对账、任务归类，响应中的 data 会原样返回该值。
postback_url	string	否	任务完成后，平台将以 POST 方式把 gzip 压缩后的结果发送到该地址。支持变量 $id 与 $tag。特殊字符会 URL 编码。
postback_data	string	条件填	当传 postback_url 时填。可选：regular、html。表示发送到回调地址的数据类型。
pingback_url	string	否	任务完成后，平台将以 GET 方式通知该地址。支持变量 $id 与 $tag。特殊字符会 URL 编码。

stop_crawl_on_match 目标对象字段

字段名	类型	填	说明
match_value	string	是	目标域名、子域名或通符表达式。域名或子域名不要带协议头。示例：本平台.com、/blog/post-*
match_type	string	是	匹方式。可选：domain（精确域名或子域名）、with_subdomains（主域名及子域名）、wildcard（通符）

---

语言与地区说明

• 百度搜索引擎支持语言 Chinese (Simplified) / zh_CN
• 但不强制是中文，百度仍可能返回语言的搜索结果
• 可用语言列表查询路径：/v3/serp/wp/languages
• 可用地区列表查询路径：/v3/serp/wp/locations

---

回调说明

postback_url

适合任务完成后直接接收完整结果。

• 平台会向该地址发送 POST
• 返回数据使用 gzip 压缩
• 支持在 URL 中使用：
• $id：任务 ID
• $tag：URL 编码后的任务标签

示例：

• http://your-server.com/postbackscript?id=$id
• http://your-server.com/postbackscript?id=$id&tag=$tag

pingback_url

适合接收完成通知，再由你自行根据任务 ID 获取结果。

• 平台会向该地址发送 GET
• 同样支持 $id 和 $tag 变量

示例：

• http://your-server.com/pingscript?id=$id
• http://your-server.com/pingscript?id=$id&tag=$tag

---

响应结构

接口返回 JSON tasks 数组，每个任务对应一条创建结果。

顶层响应字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码。完整错误码请参考 /v3/appendix/errors
status_message	string	通用状态说明
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数
tasks_error	integer	返回错误的任务数
tasks	array	任务结果数组

tasks 数组字段

字段名	类型	说明
id	string	平台任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000–60000
status_message	string	任务状态说明
time	string	当前任务处理耗时
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组数量
path	array	请求路径信息
data	object	回显你提交的任务参数
result	array | null	对于任务创建接口，此处通常为 null

建议在接时完整处理 status_code、tasks_error 以及单任务级别的异常状态。

---

请求示例

cURL

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 '[
 {
 "location_code": 2156,
 "keyword": "iphone 12"
 },
 {
 "location_name": "China",
 "keyword": "best iphone ever",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]'

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"
}

payload = [
 {
 # 示例 1：最简任务
 "location_code": 2156,
 "keyword": "iphone 12"
 },
 {
 # 示例 2：带高优级和回调通知
 "location_name": "China",
 "keyword": "best iphone ever",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

resp = requests.post(url, headers=headers, json=payload, timeout=30)
print(resp.status_code)
print(resp.json)

TypeScript

import axios from "axios";

const payload = [
 {
 location_code: 2156,
 keyword: "iphone 12",
 },
 {
 location_name: "China",
 keyword: "best iphone ever",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
 },
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/wp/v2/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 data: payload,
})
 .then((response) => {
 // 任务创建结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

---

响应示例

{
 "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-182aa9de58c5",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0091 sec.",
 "cost": 0.00075,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "baidu",
 "organic",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "baidu",
 "se_type": "organic",
 "location_code": 2156,
 "keyword": "iphone 12",
 "tag": "some_string_123",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 },
 {
 "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",
 "baidu",
 "organic",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "baidu",
 "se_type": "organic",
 "location_name": "China",
 "keyword": "best iphone ever",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

---

状态码说明

通用响应状态

状态码	说明
20000	请求成功
40006	单次 POST 中的任务数 100，出部分未被接受

任务状态

状态码	说明
20100	任务已创建

更多状态码与错误信息请参考 /v3/appendix/errors。

使用建议

1. 批量提交时控制单次任务数

• 每次最多提交 100 个任务
• 更大批量请分批发送，触发 40006

2. 优使用 location_code 和 language_code

• 参数更稳定，便于程序自动化处理
• location_coordinate 适合近似定位，不建议用于高精度地域实验

3. 谨开启 get_website_url

• 虽然可以直接获得真实落地页
• 但费用会提升至原来的 10 倍，适合重点而非量监控

4. 分页抓取时结合 depth 与 max_crawl_pages

• depth 决定要多少条结果
• max_crawl_pages 决定最多翻多少页
• 两一起能更好地控制数据量与成本

5. 异步任务优使用回调机制

• 有服务端接收能力时，建议 pingback_url 或 postback_url
• 可减少主动轮询频率，提高任务处理效率

实用场景

• 监控品牌词排名：按地区和设备提交品牌任务，持续追踪百度自然结果中的品牌官网、百科、论坛等位置。
• 分析竞品搜索占位：针对核心行业词抓取 SERP，识别竞品站点是否前 10/前 50，为和投放策略提供依据。
• 评估地域化 SEO 表现：使用不同 location_code 提交同一，比较各城市或国家下的排名差异，定位区域优化机会。
• 发现真实落地页链路：在重点任务中开启 get_website_url，解析百度跳转链接背后的真实页面，便于落地页归因和竞品页面收集。
• 创建命中即停的监控任务：通过 stop_crawl_on_match 在目标域名出现时停止翻页，降低无效抓取成本，适合“是否已结果页”的快速监测。