提交 WordPress V2 SERP 任务

本接口用于创建 WordPress 搜索结果页（SERP）抓取任务。接口可返回最多前 100 条搜索结果，并根据所选地区与语言生成对应结果。

支持两种任务优级：

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

接口地址

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

计费说明

在创建任务时计费。

参考价约 ¥0.0240 / 次 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

补说明：

• 每分钟最多可发起 2000 次 API 调用
• 每次 POST 最多 100 个任务
• 若单次请求中任务数 100，出部分将返回错误 40006
• 当 depth > 100 且搜索引擎返回 100 条结果时，可能产生额外费用
• 账户按每 100 条结果一个 SERP 单计费
• 若设定的 depth 大于返回结果数，差额费用会自动退回到账户余额

请求格式

• 请求方法：POST
• Content-Type：application/json
• 请求体为 JSON 数组 格式：[{ ... }]
• 编码：UTF-8

结果获取方式

任务创建后，可通过任务唯一标识 id 获取结果。

也可以在创建任务时指定以下回调方式：

• pingback_url：任务完成后，平台向该地址发起 GET 请求通知
• postback_url：任务完成后，平台将结果以 gzip 压缩后的 POST 请求推送到该地址

注意事项：

• 若回调接收服务器在 10 秒未响应，请求会因时中断 -时后的任务可在 /v3/serp/google/images/tasks_ready/ 列表中继续获取
• pingback_url 与 postback_url 中可使用 $id 和 $tag 占位符
• 平台发送请求前会自动替换为真实值
• URL 中特殊字符会进行 URL 编码，例如 # 会被编码为 %23

主要请求参数

字段名	类型	说明
keyword	string	填。搜索，最长 700 个字符。请求中的 %## 会被解码，+ 会被解码为空格；若本身需要 %，请写为 %25；若需要 +，请写为 %2B。若 allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site: 等搜索运算符，则该任务费用按 5 倍计算。 cache: 的查询不受支持，会返回校验错误。
location_code	integer	当未提供 location_name 或 location_coordinate 时填。搜索地区代码。若使用该字段，则无需再传 location_name 或 location_coordinate。可通过 /v3/serp/wp/locations 获取可用地区列表。示例：2840
language_code	string	当未提供 language_name 时填。搜索语言代码。若使用该字段，则无需再传 language_name。可通过 /v3/serp/wp/languages 获取可用语言列表。示例：en
depth	integer	可选。解析深度，即需要抓取的结果数。默认 100，最大 700。 100 可能触发额外计费。
priority	integer	可选。任务优级。1 为普通优级，2 为高优级。高优级会产生额外费用。
pingback_url	string	可选。任务完成后的通知地址，平台会向该地址发送 GET 请求。支持 $id 和 $tag 占位。示例：http://your-server.com/pingscript?id=$id
postback_url	string	可选。任务完成后的结果推送地址，平台会将结果以 gzip 压缩格式通过 POST 请求发送到该地址。支持 $id 和 $tag 占位。
postback_data	string	当设置 postback_url 时填。指定推送结果的数据类型。可选值：advanced、html

附加请求参数

字段名	类型	说明
location_name	string	当未提供 location_code 或 location_coordinate 时填。搜索地区完整名称。若使用该字段，则无需再传 location_code 或 location_coordinate。示例：London,England,United Kingdom
language_name	string	当未提供 language_code 时填。搜索语言完整名称。若使用该字段，则无需再传 language_code。示例：English
os	string	可选。设备操作系统。本接口提供桌面端结果。可选值：windows、macos。默认：windows
tag	string	可选。自定义任务标识，最长 255 字符。可用于将任务与业务系统中的记录进行。返回结果中的 data 对象会该值。
max_crawl_pages	integer	可选。最大抓取页数，最大值 100。该参数与 depth 互补使用。
search_param	string	可选。附加搜索参数，用于扩展查询条件。
url	string	可选。直接传搜索 URL，平台会自动解析为对应字段。该方式处理难度较高，且要求 URL 中已准确语言和地区信息，通常不建议优使用。
location_coordinate	string	当未提供 location_name 或 location_code 时填。GPS 坐标，格式为 "latitude,longitude,radius"。经纬度最多 7 位小数；radius 最小 199.9（毫米），最大 199999（毫米）。示例：53.476225,-2.243572,200
se_domain	string	可选。搜索引擎域名。通常平台会根据地区和语言自动选择域名，也可手动指定，例如：google.co.uk、google.com.au、google.de

响应字段说明

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段名	类型	说明
version	string	API 当前版本
status_code	integer	通用状态码
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	URL 路径
data	object	回显创建任务时传的参数
result	array	结果数组。对于任务创建接口，该值通常为 null

请求示例

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 '[
 {
 "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://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

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 = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert einstein",
 "priority": 2,
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "url": "https://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript

import axios from "axios";

const payload = [
 {
 language_name: "English",
 location_code: 2840,
 location_name: "United States",
 keyword: encodeURI("albert einstein"),
 priority: 2
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/google/images/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);
 });

响应示例

{
 "version": "0.1.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0818 sec.",
 "cost": 0.0045,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "01291721-1535-0066-0000-2f3f1cb7f798",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0043 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert enstein",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 },
 {
 "id": "01291721-1535-0066-0000-2e7a8bf7302c",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0050 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert enstein",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "tag": "some_string_123",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 },
 {
 "id": "01291721-1535-0066-0000-ed3110168d43",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0040 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "url": "https://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理

• 20000：请求成功
• 20100：任务已创建
• 40006：单次 POST 中任务数量上限

建议对以下场景做好异常处理：

• 参数缺失或格式错误
• 回调地址不可访问或响应时 -过频率限制或任务数量限制
• 查询词不支持的搜索运算符，如 cache:

更多错误码可参考 /v3/appendix/errors。

使用说明补

• 本接口返回桌面端结果
• 若未指定 se_domain，平台会根据地区与语言自动选择合适域名
• 推荐优使用 keyword + location + language 方式创建任务，而不是直接使用 url
• max_crawl_pages 与 depth 需结合使用，以控制翻页抓取范围与结果数量

实用场景

• 批量提交抓取任务：按国家、语言批量创建 SERP 任务，用于监控不同市场下的搜索结果差异。
• 追踪地区化搜索表现：结合 location_code 或 location_coordinate，查看同一在不同城市或商圈的结果分布，本地 SEO 优化。
• 加速高价值采集：对重点词使用 priority=2，更快拿到结果，适合竞品监控、热点追踪等时效性场景。
• 通过回调自动接收结果： pingback_url 或 postback_url，在任务完成后自动处理流程，减少轮询成本。
• 测试复杂搜索运算符效果：利用高级查询语法（如 site:、intitle:）分析索引覆盖与竞争页面，支持更细颗粒度的 SEO 研究。