设置好搜自然搜索结果任务

本接口使用 POST 方法，通过 /v3/serp/haosou/organic/task_post 创建好搜自然搜索结果（SERP）任务，并返回任务 ID。接口最多返回前 10 条搜索结果，结果受、语言、设备及请求参数影响。

好搜任务支持两种执行优级：

1：普通优级，默认值
2：高优级，执行速度更快，但会产生额外费用

由于搜索引擎响应时间较长，好搜任务的执行时间可能比 SERP 任务更长。

接口信息

http

POST https://api.seermartech.cn/v3/serp/haosou/organic/task_post

所有请求体使用 UTF-8 编码的 JSON 格式，并且顶层结构是任务数组：

json

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

调用限制：

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

每次请求最多 100 个任务。 -过 100 个任务的部分将返回错误码 40006。
任务创建成功后，可通过返回的 id 查询任务结果。
也可以通过 postback_url 或 pingback_url 接收任务完成通知。
如果回调服务器在 10 秒未响应，连接将因时中断，任务会转 tasks_ready 列表。

计费说明

本接口在成功提交任务时计费。

以下可能产生额外费用：

高级搜索操作符时，单任务费用乘以 5。
使用高优级 priority: 2 时，会额外计费。
设置 calculate_rectangles: true 时，单任务费用乘以 2。
depth 大于 10 时，可能每 10 条结果增加费用。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

如果请求的 depth 大于返回的结果数量，未使用部分产生的费用将自动退回账户余额。

请求参数

参数	类型	填	说明
`keyword`	string	是	搜索，最长 700 个字符。参数中的 `%##` 会被解码，`+` 会被解码为空格。如需在中使用 `%`，请编码为 `%25`。
`priority`	integer	否	任务优级：`1` 普通优级，默认值；`2` 高优级，执行更快但会额外计费。
`depth`	integer	否	SERP 解析深度，即请求的结果数量。默认 `10`，最大 `700`。每 10 条结果为一个计费单位。
`language_name`	string	条件填	搜索引擎语言的完整名称。未指定 `language_code` 时填。示例：`English`。
`language_code`	string	条件填	搜索引擎语言代码。未指定 `language_name` 时填。示例：`en`。
`device`	string	否	设备类型，可选 `desktop`、`mobile`。默认值：`desktop`。
`os`	string	否	设备操作系统。`desktop` 可选 `windows`、`macos`，默认 `windows`；`mobile` 可选 `android`、`ios`，默认 `android`。
`calculate_rectangles`	boolean	否	是否在高级结果中计算像素排名。默认 `false`。设为 `true` 时，单任务费用乘以 2。
`browser_screen_width`	integer	否	浏览器屏幕宽度，用于计算像素排名。在 `calculate_rectangles` 为 `true` 时生效。默认值：桌面端 `1920`，Android 移动端 `360`，iOS 移动端 `375`。
`browser_screen_height`	integer	否	浏览器屏幕高度，用于计算像素排名。在 `calculate_rectangles` 为 `true` 时生效。默认值：桌面端 `1080`，Android 移动端 `640`，iOS 移动端 `812`。
`browser_screen_resolution_ratio`	integer	否	浏览器屏幕分辨率比例，用于计算像素排名。在 `calculate_rectangles` 为 `true` 时生效。默认值：桌面端 `1`，Android 和 iOS 移动端均为 `3`。
`search_param`	string	否	搜索查询的附加参数。例如 `&adv_t=d` 表示获取最近一天的结果。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样出现在响应的 `data` 数组中，可用于任务与业务记录。
`postback_url`	string	否	任务完成后接收结果的 URL。本平台将以 gzip 压缩格式向该地址发送 POST 请求。URL 中可使用 `$id` 和 `$tag` 占位符。
`postback_data`	string	条件填	`postback_url` 的返回数据类型。指定 `postback_url` 时填，可选 `regular`、`advanced`、`html`。
`pingback_url`	string	否	任务完成通知 URL。本平台将以 GET 请求访问该地址。URL 中可使用 `$id` 和 `$tag` 占位符。

特殊规则

如果 keyword 中以下高级搜索操作符，单任务费用将乘以 5：

text

allinanchor:
allintext:
allintitle:
allinurl:
define:
filetype:
id:
inanchor:
info:
intext:
intitle:
inurl:
link:
related:
site:

cache: 的查询不受支持，并会返回参数校验错误。

语言参数

language_name 与 language_code 至少指定一个，二同时指定时建议保持一致。

可通过以下接口获取好搜支持的语言列表：

http

GET https://api.seermartech.cn/v3/serp/haosou/languages

示例：

json

{
  "language_name": "English",
  "language_code": "en"
}

回调 URL 占位符

postback_url 和 pingback_url 支持以下占位符：

$id：任务的 ID
$tag：经过 URL 编码的标签值

示例：

text

https://your-server.com/postbackscript?id=$id
https://your-server.com/postbackscript?id=$id&tag=$tag

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/haosou/organic/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "keyword": "albert einstein"
    },
    {
      "language_name": "Chinese (Simplified)",
      "keyword": "北京的购物中心",
      "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/haosou/organic/task_post"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "language_code": "en",
        "keyword": "albert einstein",
    },
    {
        "language_name": "Chinese (Simplified)",
        "keyword": "北京的购物中心",
        "priority": 2,
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
    },
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "错误。状态码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    language_code: "en",
    keyword: "albert einstein",
  },
  {
    language_name: "Chinese (Simplified)",
    keyword: "北京的购物中心",
    priority: 2,
    tag: "some_string_123",
    pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/serp/haosou/organic/task_post",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error.response?.data || error.message);
  });

响应说明

接口返回 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` 数组中返回错误的任务数量。
`tasks`	array	已创建任务的详细信息。

`tasks` 数组中的字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务提交或执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。任务创建阶段通常为 `0`。
`path`	array	任务结果路径。
`data`	array/object	请求时提交的参数及系统补参数。
`result`	array/null	任务结果。任务刚创建时为 `null`。

响应示例

json

{
  "version": "0.1.20210105",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1043 sec.",
  "cost": 0.00225,
  "tasks_count": 2,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01151701-1535-0066-0000-5107d0b3aeaf",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0075 sec.",
      "cost": 0.0015,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "haosou",
        "se_type": "organic",
        "keyword": "albert einstein",
        "language_code": "en",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    },
    {
      "id": "01151701-1535-0066-0000-5107d0b3aeaf",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0075 sec.",
      "cost": 0.0015,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "haosou",
        "se_type": "organic",
        "keyword": "北京的购物中心",
        "language_name": "Chinese (Simplified)",
        "priority": 2,
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

状态码与异常处理

建议在业务系统中同时判断 HTTP 状态、顶层 status_code、任务级 status_code 及 tasks_error，并针对以下进行处理：

请求体不是 JSON 数组。
单次提交任务数 100 个。
language_name 与 language_code 均未提供。
不支持的 cache: 参数。
postback_url 已指定但缺少 postback_data。
回调服务器未在 10 秒响应。

实用场景

批量采集排名：为大量目标创建好搜自然结果任务，评估网站在指定搜索引擎中的可见度变化。
对比桌面端与移动端 SERP：分别提交不同 device 和 os 参数，定位移动端与桌面端排名差异及优化机会。
监测时间敏感型搜索结果：通过 search_param 设置时间范围，跟踪最近一天等短周期的热点排名。
分析搜索结果页面版位：启用 calculate_rectangles 获取结果的像素位置，评估自然结果在 SERP 页面中的位置。
构建异步排名监控流程： pingback_url 或 postback_url，在任务完成后自动接收结果，减少轮询开销并提升监控时效。

设置好搜自然搜索结果任务 ​

接口信息 ​

计费说明 ​

请求参数 ​

特殊规则 ​

语言参数 ​

回调 URL 占位符 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks 数组中的字段 ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​

设置好搜自然搜索结果任务

接口信息

计费说明

请求参数

特殊规则

语言参数

回调 URL 占位符

请求示例

curl

Python

TypeScript

响应说明

顶层响应字段

`tasks` 数组中的字段

响应示例

状态码与异常处理

实用场景