Bing SERP 任务创建

使用 POST /v3/serp/wp/v2/task_post 创建 Bing 搜索结果页（SERP）采集任务。搜索结果受指定的地点、语言、设备和操作系统影响。任务创建成功后，可通过任务唯一标识 id 获取结果，也可 Pingback 或 Postback 回调接收完成通知或结果数据。

http

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

平台限流以认证说明中的 30/60/120 次/分钟规则为准；单次 POST 请求最多可 100 个任务。 100 个任务的部分将返回错误码 40006。

任务优级支持：

1：普通优级，默认值。
2：高优级，执行速度更快，额外收费。

账户在成功创建任务时扣费。depth过 10 且搜索引擎返回 10 条结果时，可能产生额外费用；高优级和像素排名计算也会增加费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

POST 请求体为 UTF-8 编码的 JSON 数组：

json

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

主要参数

参数	类型	填	说明
`keyword`	string	是	搜索，最长 700 个字符。请求中的 `%##` 会被解码，`+` 会被解码为空格。如需搜索字面量 `%`，请传 `%25`；如需搜索字面量 `+`，请传 `%2B`。
`location_code`	integer	条件填	搜索地点代码。未传 `location_name` 或 `location_coordinate` 时填。使用该参数时无需传另外两种地点参数。例如：`2840`。地点列表可通过 `/v3/serp/wp/locations` 获取。
`language_code`	string	条件填	搜索语言代码。未传 `language_name` 时填。例如：`en`。语言列表可通过 `/v3/serp/wp/languages` 获取。
`depth`	integer	否	SERP 解析深度，即返回结果数量。默认值：`10`；最大值：`700`。每个最多 10 条结果的 SERP 单独计费。
`priority`	integer	否	任务优级：`1` 为普通优级（默认），`2` 为高优级。高优级任务会产生额外费用。
`device`	string	否	设备类型，可选 `desktop`、`mobile`。默认值：`desktop`。
`pingback_url`	string	否	任务完成后的通知地址。本平台会向该地址发送 GET 请求。支持 `$id` 占位符和 URL 编码后的 `$tag` 占位符，例如 `https://your-server.com/pingscript?id=$id&tag=$tag`。URL 中的特殊字符会自动编码，例如 `#` 会转换为 `%23`。
`postback_url`	string	否	任务完成后接收结果的地址。本平台会向该地址发送 POST 请求，结果采用 gzip 压缩。支持 `$id` 和 URL 编码后的 `$tag` 占位符。
`postback_data`	string	条件填	指定 `postback_url` 时填，定义回调结果的数据类型。可选：`regular`、`advanced`、`html`。

> 回调服务器应在 10 秒响应。该时间未响应时，连接将因时中止，任务会转 /v3/serp/bing/organic/tasks_ready/ 列表。

附加参数

参数	类型	填	说明
`location_name`	string	条件填	搜索地点称。未传 `location_code` 或 `location_coordinate` 时填。例如：`London,England,United Kingdom`。
`language_name`	string	条件填	搜索语言称。未传 `language_code` 时填，例如：`English`。
`os`	string	否	设备操作系统。`device=desktop` 时可选 `windows`、`macos`，默认 `windows`；`device=mobile` 时可选 `android`、`ios`，默认 `android`。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会在响应任务对象的 `data` 中原样返回，可用于业务记录。
`stop_crawl_on_match`	array	否	到达指定目标时停止翻页采集的规则数组，最多 10 个目标对象。响应会保留至命中 `match_value` 所在的 SERP 结果。达到条件前已采集的每个 SERP 均会计费。
`match_type`	string	条件填	指定 `stop_crawl_on_match` 时填。匹类型：`domain`（指定域名或子域名）、`with_subdomains`（主域名及子域名）、`wildcard`（通符模式）。
`match_value`	string	条件填	指定 `stop_crawl_on_match` 时填。目标域名、子域名或通符值。域名不得协议头，例如 `example.com`；通符示例：`/blog/post-*`。
`max_crawl_pages`	integer	否	最大采集搜索结果页数。默认值：`1`；最大值：`100`。该参数与 `depth`合决定最终采集范围。
`search_param`	string	否	搜索请求的附加参数。
`calculate_rectangles`	boolean	否	是否在高级结果中计算 SERP素的像素排名，即结果摘要距屏幕左上角的距离。默认值：`false`。启用该功能的参考附加费约 ¥0.0043 / 次；扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`browser_screen_width`	integer	否	自定义浏览器屏幕宽度，范围 `240-9999`。在 `calculate_rectangles=true` 时有效。默认值：桌面端 `1920`、Android 移动端 `360`、iOS 移动端 `375`。
`browser_screen_height`	integer	否	自定义浏览器屏幕高度，范围 `240-9999`。在 `calculate_rectangles=true` 时有效。默认值：桌面端 `1080`、Android 移动端 `640`、iOS 移动端 `812`。
`browser_screen_resolution_ratio`	number	否	自定义浏览器屏幕分辨率比例，范围 `0.5-3`。在 `calculate_rectangles=true` 时有效。默认值：桌面端 `1`，Android 与 iOS 移动端均为 `3`。
`url`	string	否	搜索请求完整 URL。本接口会自动解析的查询参数。此方式需在 URL 中准确传地点和语言，处理复杂度较高，通常建议优使用 `keyword`、地点和语言参数。
`location_coordinate`	string	条件填	GPS 坐标，格式为 `"latitude,longitude"`。未传 `location_code` 或 `location_name` 时填。经纬度最多各保留 7 位小数，例如：`53.476225,-2.243572`。

`stop_crawl_on_match` 示例

json

[
  {
    "keyword": "rank checker",
    "location_code": 2840,
    "language_code": "en",
    "max_crawl_pages": 10,
    "stop_crawl_on_match": [
      {
        "match_type": "with_subdomains",
        "match_value": "example.com"
      }
    ]
  }
]

请求示例

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/task_post"

# 请求体为任务对象组成的 JSON 数组
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein"
    },
    {
        # 高优级任务，并在完成后发送 GET 回调通知
        "language_name": "English",
        "location_name": "United States",
        "keyword": "albert einstein",
        "priority": 2,
        "tag": "campaign_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    }
]

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()

if result["status_code"] == 20000:
    print(result)
else:
    print(f'错误码：{result["status_code"]}，消息：{result["status_message"]}')

TypeScript

typescript

import axios from "axios";

// 每个数组对应一个独立任务
const tasks = [
  {
    language_code: "en",
    location_code: 2840,
    keyword: "albert einstein"
  },
  {
    // 使用完整搜索 URL 创建任务，并通过 Postback 接收 HTML 结果
    url: "https://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGE",
    postback_data: "html",
    postback_url: "https://your-server.com/postbackscript"
  }
];

async function createTasks() {
  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"
        }
      }
    );

    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
}

createTasks();

响应说明

接口返回 JSON 对象 tasks 数组对应本次提交的任务。任务创建成功后，result 为 null；请使用返回的 id 查询后续结果，或已的回调通知。

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	局状态码。建议针对异常状态建立错误处理机制。
`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	创建任务时提交的参数，以及接口补的默认参数。
`tasks[].result`	array / null	任务结果。任务刚创建时为 `null`。

响应示例

json

{
  "version": "0.1.20200129",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2539 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.0055 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": "01291939-1535-0066-0000-170c2bafbc0f",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0038 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://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGE",
        "postback_data": "html",
        "postback_url": "https://your-server.com/postbackscript",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

实用场景

监控品牌词排名：按国家、城市、语言和设备定期创建品牌任务，及时发现自然搜索可见度波动。
追踪竞品位置：结合 stop_crawl_on_match 追踪竞品域名首次出现的位置，降低深度采集带来的无效成本。
评估移动端搜索体验：指定 device=mobile、操作系统和屏幕参数，分析移动端 SERP 与桌面端结果的差异。
构建大规模监测队列：一次提交最多 100 个任务，并通过 tag 将任务与项目、客户或分组。
采集页面视觉位置信息：启用 calculate_rectangles 获取 SERP素像素排名，用于评估结果在首屏中的可见性。

Bing SERP 任务创建 ​

请求参数 ​

主要参数 ​

附加参数 ​

stop_crawl_on_match 示例 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

响应示例 ​

实用场景 ​

Bing SERP 任务创建

请求参数

主要参数

附加参数

`stop_crawl_on_match` 示例

请求示例

curl

Python

TypeScript

响应说明

响应示例

实用场景