提交 Yahoo SERP 任务

POST /v3/serp/wp/v2/task_post

接口说明

该接口用于提交 Yahoo 搜索结果抓取任务。返回结果会基于你指定的地域和语言生成。

接口支持两种执行优级：

1：普通优级（默认）
2：高优级

高优级通常会更快执行，但费用更高。

请求地址

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

说明：该接口路径属于容路径，/v3/serp/wp/v2/task_post 需按原样使用。

计费与频率限制

在成功创建任务时扣费
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
参考价约 ¥0.0240 / 次
若使用高优级、较大抓取深度、多页抓取等，费用会相应增加

调用限制：

每分钟最多提交 2000 次 API 调用
每个 POST 请求最多 100 个任务
如果单次请求 100 个任务，出部分会返回错误 40006

请求格式

所有 POST 数据使用 UTF-8 编码的 JSON，并且请求体为数组格式：

json

[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]

结果获取方式

任务创建成功后，你可以通过以下方式获取结果：

使用返回的任务唯一标识 id 主动获取结果
在创建任务时设置：

postback_url：任务完成后，本平台会向该地址发送结果
pingback_url：任务完成后，本平台会向该地址发送完成通知

注意事项：

如果你的服务器在 10 秒未响应，连接会因时中断 -时后，任务会被转移到“Tasks Ready”列表，供你后续主动拉取
postback_url 发送的是 POST 请求，结果使用 gzip 压缩
pingback_url 发送的是 GET 请求用于通知任务完成

请求参数

任务级参数说明

字段	类型	说明
`url`	string	直接传搜索 URL。可选。系统会自动解析成对应参数。此方式处理难度较高，且在 URL 中准确语言和地域信息，通常不推荐。示例：`https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8`
`keyword`	string	。填（除非使用可替代的完整 `url` 方式）。最多 `700` 个字符。所有 `%##` 会被解码，`+` 会被解码为空格。如需传字面量 `%`，请写成 `%25`；如需传字面量 `+`，请写成 `%2B`。
`priority`	integer	任务优级。可选。`1` = 普通优级（默认），`2` = 高优级。高优级会产生额外费用。
`location_name`	string	搜索地域名。若未提供 `location_code` 或 `location_coordinate`，则此字段填。使用该字段时，无需再传 `location_code` 或 `location_coordinate`。示例：`London,England,United Kingdom`。可通过 `/v3/serp/wp/locations` 获取地域列表。
`location_code`	integer	搜索地域编码。若未提供 `location_name` 或 `location_coordinate`，则此字段填。使用该字段时，无需再传 `location_name` 或 `location_coordinate`。示例：`2840`。可通过 `/v3/serp/wp/locations` 获取地域列表。
`location_coordinate`	string	地理坐标定位。若未提供 `location_name` 或 `location_code`，则此字段填。格式：`latitude,longitude,radius`。`latitude` 和 `longitude` 最多支持 `7` 位小数；`radius` 最小值 `199.9`（毫米），最大值 `199999`（毫米）。示例：`53.476225,-2.243572,200`
`language_name`	string	搜索语言名。若未提供 `language_code`，则此字段填。使用该字段时，无需再传 `language_code`。示例：`English`。可通过 `/v3/serp/wp/languages` 获取语言列表。
`language_code`	string	搜索语言代码。若未提供 `language_name`，则此字段填。使用该字段时，无需再传 `language_name`。示例：`en`。可通过 `/v3/serp/wp/languages` 获取语言列表。
`device`	string	设备类型。可选。可选值：`desktop`、`mobile`。默认：`desktop`
`os`	string	设备操作系统。可选。若 `device=desktop`，可选 `windows`、`macos`，默认 `windows`；若 `device=mobile`，可选 `android`、`ios`，默认 `android`
`se_domain`	string	搜索引擎域名。可选。系统会根据地域和语言自动选择域名，你也可以手动指定。示例：`au.search.yahoo.com`、`uk.search.yahoo.com`、`ca.search.yahoo.com`
`depth`	integer	抓取深度，即返回的 SERP 结果数量。可选。默认：`6`；最大：`700`。按每个 SERP 计费。Yahoo 的单页结果可能少于 10 条，因此将 `depth` 设为高于默认值时，可能触发额外抓取和额外费用。
`max_crawl_pages`	integer	最多抓取的结果页数。可选。默认：`1`；最大：`100`。该参数与 `depth`合使用同决定抓取范围。
`search_param`	string	搜索附加参数。可选。用于补控制 Yahoo 查询行为。
`stop_crawl_on_match`	array	命中目标后停止抓取。可选。为目标对象数组，最多支持 `10` 个对象。若设置，本接口会返回直到命中 `match_value` 为止的 SERP 结果（含命中项）。在命中前抓取的每个 SERP 都会计费。
`tag`	string	自定义任务标识。可选。最多 `255` 个字符。可用于将任务与业务系统记录，响应中的 `data` 对象会原样返回该值。
`postback_url`	string	结果回调地址。可选。任务完成后，本平台会向该地址发送 gzip 压缩后的 POST 结果。支持使用 `$id` 和 `$tag` 作为变量占位符。示例：`http://your-server.com/postbackscript?id=$id`、`http://your-server.com/postbackscript?id=$id&tag=$tag`。注意：URL 中特殊字符会被自动 URL 编码，例如 `#` 会编码为 `%23`。
`postback_data`	string	回调数据类型。当设置 `postback_url` 时填。可选值：`regular`、`html`
`pingback_url`	string	完成通知地址。可选。任务完成后，本平台会向该地址发起 GET 请求。支持使用 `$id` 和 `$tag` 作为变量占位符。示例：`http://your-server.com/pingscript?id=$id`、`http://your-server.com/pingscript?id=$id&tag=$tag`。注意：URL 中特殊字符会被自动 URL 编码。

`stop_crawl_on_match` 子字段

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

响应结构

接口返回 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	本平台任务唯一标识，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 和每个任务的 status_code 分别做校验
常见成功状态：
20000：请求成功
20100：任务已创建
常见错误：
40006：单次 POST 提交的任务数 100

完整错误码体系请参考 /v3/appendix/errors。

请求示例

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 '[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert einstein",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "url": "https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

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

# POST 请求体为数组
payload = [
 {
 # 示例 1：最简单的提交方式
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 },
 {
 # 示例 2：带高优级、标签和完成通知
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert einstein",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 # 示例 3：直接使用完整搜索 URL
 "url": "https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json)

TypeScript

typescript

import axios from "axios";

const payload = [
 {
 // 示例 1：最简单的任务提交
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein"
 },
 {
 // 示例 2：高优级任务，完成后通过 pingback 通知
 language_name: "English",
 location_name: "United States",
 keyword: "albert einstein",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 // 示例 3：通过完整搜索 URL 提交
 url: "https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8",
 postback_data: "html",
 postback_url: "https://your-server.com/postbackscript"
 }
];

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);
 });

响应示例

json

{
 "version": "0.1.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2271 sec.",
 "cost": 0.0045,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "11141653-0696-0066-0000-fa25e0da658e",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0052 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "wp",
 "v2",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 },
 {
 "id": "11141653-0696-0066-0000-fa25e0da658e",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0053 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "wp",
 "v2",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert enstein",
 "priority": "2",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "tag": "some_string_123",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 },
 {
 "id": "11141653-0696-0066-0000-fa25e0da658e",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0053 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "wp",
 "v2",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "url": "https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

使用建议

优使用 keyword + location + language 的结构化方式创建任务，稳定性通常高于直接传 url
如果需要尽快消费结果，建议结合 pingback_url 或 postback_url
若需控制成本，建议谨设置 depth、max_crawl_pages 与 priority
如需按目标站点是否出现来提前停止抓取，可使用 stop_crawl_on_match

实用场景

监控排名：按国家、语言、设备定期提交查询任务，持续追踪品牌词或核心业务词在 Yahoo 中的排名变化。
分析本地化搜索表现：通过 location_code 或 location_coordinate 指定区域，比较不同城市或国家下同一的结果差异。
追踪竞品：使用 stop_crawl_on_match 查找指定域名或子域名何时出现在结果中，快速评估竞品自然可见度。
搭建异步采集流程：结合 pingback_url 或 postback_url，在任务完成后自动接收通知或结果，减少轮询成本。
批量抓取 SERP 数据：单次请求提交多个任务，用于构建库、SERP 样本集或搜索结果分析数据仓库。

提交 Yahoo SERP 任务 ​

接口说明 ​

请求地址 ​

计费与频率限制 ​

请求格式 ​

结果获取方式 ​

请求参数 ​

任务级参数说明 ​

stop_crawl_on_match 子字段 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

状态码与错误处理 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

使用建议 ​

实用场景 ​