提交 WP V2 SERP 任务

该接口用于创建 WP V2 SERP 抓取任务，并根据指定的地区与语言返回对应搜索结果。

WP V2 SERP API 支持按位置与语言维度采集搜索结果。任务执行优级分为两档：

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

说明：计费按返回结果分页深度计算。桌面端每 20 条结果为一个计费单位，移动端每 10 条结果为一个计费单位。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

接口地址

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

请求说明

请求方法：POST
请求体格式：JSON
编码：UTF-8
请求体为 JSON 数组格式：[{ ... }]

每分钟最多可发送 2000 次 API 调用；每次 POST 最多提交 100 个任务。若单次请求中任务数 100，出部分会返回错误码 40006。

任务创建成功后，你可以通过返回的唯一任务 ID 获取结果；也可以在创建任务时设置：

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

如果你的服务器在 10 秒未响应回调，请求会因时中断，该任务会 /v3/serp/google/local_finder/tasks_ready/ 列表主动拉取。

计费说明

在任务成功创建时计费
桌面端：每 20 条结果为一个计费单位
移动端：每 10 条结果为一个计费单位
当 depth过桌面 20 或移动 10 时，如搜索引擎返回更多结果，可能产生额外费用
如果设置的 depth 高于返回结果数量，差额会自动返还到账户余额
高优级任务会额外收费

由于原始文档未给出固定单价，本文不提供固定人民币参考价。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

主要参数

字段	类型	说明
`keyword`	string	填。搜索，最长 `700` 个字符。`%##` 会被解码，字符 `+` 会被解码为空格。如需传字面量 `%`，请写为 `%25`；如需传字面量 `+`，请写为 `%2B`。
`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	解析深度，可选。表示要抓取的结果数量。桌面端默认 `20`、最大 `500`；移动端默认 `10`、最大 `350`。
`priority`	integer	任务优级，可选。`1` 为普通优级，`2` 为高优级。高优级会更快执行，但费用更高。
`device`	string	设备类型，可选。支持：`desktop`、`mobile`。默认：`desktop`
`pingback_url`	string	任务完成通知地址，可选。任务完成后，本平台会向该地址发送 `GET` 请求。支持在 URL 中使用 `$id` 与 `$tag` 变量，例如：`https://your-server.com/pingscript?id=$id&tag=$tag`。特殊字符会自动进行 URL 编码。
`postback_url`	string	结果推送地址，可选。任务完成后，本平台会将 `gzip` 压缩结果通过 `POST` 请求发送到该地址。支持使用 `$id` 与 `$tag` 变量。特殊字符会自动进行 URL 编码。
`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	设备操作系统，可选。若 `device=desktop`，可选：`windows`、`macos`，默认 `windows`；若 `device=mobile`，可选：`android`、`ios`，默认 `android`
`tag`	string	自定义任务标识，可选，最大 `255` 个字符。便于将任务与业务系统中的记录。返回结果中的 `data` 对象会带回该值。
`location_coordinate`	string	GPS 坐标定位。如果未提供 `location_name` 或 `location_code`，则此字段填。格式为 `"latitude,longitude,zoom"`。若不传 `zoom`，默认 `9z`。`latitude` 与 `longitude` 最多 `7` 位小数；`zoom` 最小 `4z`，最大 `18z`。示例：`52.6178549,-155.352142,18z`
`min_rating`	integer	按最低评分过滤结果，可选。桌面端可选值：`3.5`、`4`、`4.5`；移动端可选值：`2`、`2.5`、`3`、`3.5`、`4`、`4.5`
`time_filter`	string	按营业时间过滤结果，可选。支持以下值：`"open_now"`、`"24_hours"`、`"$day_value"`、`"$day_value;$time_value"`。 `$day_value` 可为 `monday` 至 `sunday`，`$time_value` 可为 `"00"` 至 `"23"`。示例：`"tuesday;18"`。注意：搜索引擎仍可能返回部分不符合该过滤条件的结果。

请求示例

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": "local nail services",
 "min_rating": 4.5,
 "time_filter": "monday"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "local nail services",
 "min_rating": 4.5,
 "time_filter": "monday",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]'

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

data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "local nail services",
 "min_rating": 4.5,
 "time_filter": "monday"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "local nail services",
 "min_rating": 4.5,
 "time_filter": "monday",
 "priority": 2,
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

resp = requests.post(url, headers=headers, json=data)
print(resp.json)

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "local nail services",
 min_rating: 4.5,
 time_filter: "monday"
 }
];

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: postArray
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应结构

接口返回 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	平台唯一任务 ID，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	对于任务提交接口，该值通常为 `null`

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

响应示例

json

{
 "version": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2539 sec.",
 "cost": 0.1,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "11141653-0696-0066-0000-fa25e0da658d",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0000 sec.",
 "cost": 0.05,
 "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.0000 sec.",
 "cost": 0.05,
 "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": "local nail services",
 "priority": 2,
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "tag": "some_string_123",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码说明

状态码	含义
`20000`	请求成功
`20100`	任务已创建
`40006`	单次请求中的任务数 `100`

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

使用建议

批量提交时，建议每次请求控制在 100 个任务
如需更快结果返回，可使用 priority=2，但会增加费用
如需异步处理，优使用 pingback_url 或 postback_url
使用 tag 将任务与工单、分组或项目 ID 对齐，便于后续回查
当需要按评分或营业时间筛选本地服务类结果时，可组合使用 min_rating 与 time_filter

实用场景

监控本地服务词排名：提交指定城市与语言下的任务，持续跟踪本地服务类查询的搜索结果变化，评估门店或客户在区域搜索中的可见度。
筛选高评分商家结果：结合 min_rating 过滤结果，只高评分商家，便于竞品调研和本地口碑分析。
分析营业时段机会：使用 time_filter 指定星期与时段，观察不同时段下的结果差异，为门店营业时间优化和投放策略提供依据。
对比桌面与移动端结果：通过 device 参数分别抓取桌面与移动 SERP，识别不同终端下的排名差异与展示机会。
建立异步采集流水线：结合 pingback_url 或 postback_url 自动接收任务完成通知与结果，降低轮询成本，提升大规模 SERP 采集效率。

提交 WP V2 SERP 任务 ​

接口地址 ​

请求说明 ​

计费说明 ​

主要参数 ​

附加参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

响应示例 ​

状态码说明 ​

使用建议 ​

实用场景 ​