设置 WordPress V2 SERP 查询任务

使用 POST /v3/serp/wp/v2/task_post 创建 WordPress V2 SERP 查询任务。本接口根据指定的地理位置、语言、设备和操作系统获取搜索结果；任务创建后，可通过任务 id 查询结果，或通过回调地址接收完成通知及结果。

text

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

任务支持两种执行优级：

1：普通优级，默认值。
2：高优级，通常执行更快，但费用更高。

在成功创建任务时计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。响应示例中 3 个普通任务的历史参考费用约为 ¥0.0324，高优级、抓取深度及翻页数量可能影响最终费用。

请求限制

平台限流以认证说明中的 30/60/120 次/分钟规则为准。

单个 POST 请求最多 100 个任务。 -出 100 个任务的部分将返回错误码 40006。
请求体使用 UTF-8 编码的 JSON 数组格式：[{ ... }]。
每个任务创建成功后会返回唯一的 id，用于后续获取结果。
若 postback_url 或 pingback_url，本平台会在任务完成时主动通知。
回调服务应在 10 秒响应；时后连接将被中止，任务结果可从已完成任务列表中获取。

请求参数

请求体为任务对象组成的 JSON 数组。每个对象代表一个独立任务。

字段	类型	填	说明
`url`	string	否	搜索查询的直接 URL。本接口会尝试从 URL 中解析查询参数、语言和地区。该方式处理复杂，建议优使用 `keyword`、位置和语言字段。示例：`https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8`。
`keyword`	string	是*	查询，最长 `700` 个字符。所有 `%##` 编码将被解码，`+` 会被解码为空格。如本身需要 `%`，请使用 `%25`；如需使用 `+`，请使用 `%2B`。使用 `url` 时可不传此字段。
`priority`	integer	否	任务优级：`1` 为普通优级，默认；`2` 为高优级。高优级任务会产生更高费用。
`location_name`	string	条件填	搜索地区名。未传 `location_code` 和 `location_coordinate` 时填。传该字段后，无需再传位置字段。示例：`London,England,United Kingdom`。可通过 `/v3/serp/wp/locations` 获取可用地区。
`location_code`	integer	条件填	搜索地区代码。未传 `location_name` 和 `location_coordinate` 时填。传该字段后，无需再传位置字段。示例：`2840`。可通过 `/v3/serp/wp/locations` 获取可用地区。
`location_coordinate`	string	条件填	GPS 坐标，格式为 `latitude,longitude,radius`。未传 `location_name` 和 `location_code` 时填。经纬度最多保留 `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`。每个搜索结果页均可能计费；由于单页结果可能少于 10 条，提高深度可能导致抓取更多页面并增加费用。
`max_crawl_pages`	integer	否	最大抓取结果页数。默认值：`1`，最大值：`100`。该参数与 `depth`合使用同控制抓取范围。
`search_param`	string	否	搜索请求附加参数，用于传递搜索引擎支持的额外查询条件。
`stop_crawl_on_match`	array	否	停止抓取目标数组，最多 `10` 个目标对象。命中目标后，响应将返回截至该匹项所在位置的结果。任务会按抓取至命中条件前的每个 SERP 计费。
`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` 对象字段

字段	类型	填	说明
`match_value`	string	是	要匹的域名、子域名或通符规则。域名或子域名不得 `http://`、`https://` 等协议前缀。示例：`example.com`、`/blog/post-*`。
`match_type`	string	是	匹类型：`domain` 表示指定域名或子域名；`with_subdomains` 表示主域名及所有子域名；`wildcard` 表示通符模式。

请求示例

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"

# 请求体为 JSON 数组；单次最多提交 100 个任务
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，并通过 Postback 接收 HTML 结果
        "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={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)

response.raise_for_status()
result = response.json()

# 实人民币扣费以该响应头为准
charge_cny = response.headers.get("X-SeerMarTech-Charge-CNY")

if result["status_code"] == 20000:
    print("任务创建成功：", result)
    print("本次扣费（人民币）：", charge_cny)
else:
    print(
        f"请求失败：{result['status_code']} - {result['status_message']}"
    )

TypeScript

typescript

import axios from "axios";

// 请求体为 JSON 数组
const tasks = [
  {
    // 通过、地区和语言创建任务
    language_name: "English",
    location_name: "United States",
    keyword: "albert einstein",
  },
];

async function createSerpTasks() {
  try {
    const response = await axios.post(
      "https://api.seermartech.cn/v3/serp/wp/v2/task_post",
      tasks,
      {
        headers: {
          Authorization: "Bearer smt_live_YOUR_KEY",
          "Content-Type": "application/json",
        },
        timeout: 30_000,
      }
    );

    const result = response.data;

    if (result.status_code === 20000) {
      console.log("任务创建成功：", result);
      console.log(
        "本次扣费（人民币）：",
        response.headers["x-seermartech-charge-cny"]
      );
    } else {
      console.error(
        `请求失败：${result.status_code} - ${result.status_message}`
      );
    }
  } catch (error) {
    console.error("调用接口异常：", error);
  }
}

createSerpTasks();

响应字段

接口成功受理请求后，返回 tasks 数组的 JSON 数据。每个任务的创建状态独立返回。

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求总体状态码。成功通常为 `20000`。应根据错误码设计异常处理逻辑。
`status_message`	string	请求总体状态信息。
`time`	string	请求处理耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	返回错误的任务数量。
`tasks`	array	任务处理结果数组。
`tasks[].id`	string	任务唯一标识，采用 UUID 格式。用于查询任务结果或回调通知。
`tasks[].status_code`	integer	单个任务状态码，范围通常为 `10000` 至 `60000`。任务成功创建时通常为 `20100`。
`tasks[].status_message`	string	单个任务状态说明，例如 `Task Created.`。
`tasks[].time`	string	单个任务处理耗时，单位为秒。
`tasks[].cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks[].result_count`	integer	`result` 数组中的数量。创建任务时通常为 `0`。
`tasks[].path`	array	请求路径信息。
`tasks[].data`	object	任务使用的参数，请求中传的字段以及默认补的 `device`、`os` 等字段。
`tasks[].result`	array / null	任务结果。创建任务阶段该字段为 `null`，任务完成后需通过任务结果接口或回调获取 SERP 数据。

响应示例

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.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_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 einstein",
        "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
    }
  ]
}

常见错误

错误码	说明	处理建议
`40006`	单次请求中的任务数量上限。	将任务拆分为多个请求，每个请求最多 `100` 个任务。
`20000`	请求已成功处理。	检查 `tasks`各任务的状态码和 `id`。
`20100`	任务已创建。	保存任务 `id`，后续查询结果或回调通知。

实用场景

监控排名：按国家、语言、设备批量创建查询任务，持续追踪目标页面在搜索结果中的可见性变化。
核查竞品覆盖：通过 stop_crawl_on_match 监测竞品域名是否出现，并在命中后停止抓取以控制采集成本。
对比移动端与桌面端结果：为同一分别设置 device 和 os，识别不同终端下的排名差异与页面展示差异。
构建自动化排名报表：使用 postback_url 在任务完成后自动接收压缩结果，减少轮询并将数据直接写报表或数据仓库。
评估地区化搜索表现：通过 location_code 或 location_coordinate 针对城市、区域或坐标范围发起查询，分析本地 SEO 策略效果。

设置 WordPress V2 SERP 查询任务 ​

请求限制 ​

请求参数 ​

stop_crawl_on_match 对象字段 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应字段 ​

响应示例 ​

常见错误 ​

实用场景 ​