提交 Haosou 自然搜索 SERP 任务

通过本接口可提交 Haosou 自然搜索结果采集任务，并返回对应任务 ID。任务完成后，可通过任务 ID 获取结果，或在创建任务时 postback_url / pingback_url 由系统主动通知。

Haosou SERP 返回所选语言、及搜索参数对应的前若干条自然搜索结果。任务支持两种优级：

1：普通优级（默认）
2：高优级（更快执行，额外计费）

说明：由于搜索引擎服务端响应较，Haosou SERP 任务的执行时间可能略高于 SERP 类型任务。

接口地址

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

计费说明

本接口在创建任务时扣费。

参考价约 ¥0.0240 / 次
高优级任务会额外加价
若 keyword 中特定高级搜索操作符，单任务费用乘以 5
若 calculate_rectangles=true，单任务费用乘以 2
depth过 10 时，若返回结果 10 条，可能产生额外扣费
若设置的 depth 高于返回数量，差额会自动退回账户余额
扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求说明

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

频率与批量限制

每分钟最多 2000 次 API 调用
单次 POST 最多 100 个任务
若单次请求中任务数 100，出部分将返回错误 40006

结果获取方式

创建任务成功后，可以通过返回的唯一任务标识 id 获取结果。

也可以在创建任务时指定以下回调地址：

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

回调时说明

如果您的服务器在 10 秒未响应，连接会因时被中断，任务会转 /v3/serp/haosou/organic/tasks_ready 列表。错误码与错误信息取决于您的服务器。

请求参数

字段名	类型	说明
`keyword`	string	填。搜索，最长 `700` 个字符。请求中的 `%##` 会被解码，`+` 会被解码为空格。如果中需要保留 `%`，请写为 `%25`。若以下搜索操作符：`allinanchor:`、`allintext:`、`allintitle:`、`allinurl:`、`define:`、`filetype:`、`id:`、`inanchor:`、`info:`、`intext:`、`intitle:`、`inurl:`、`link:`、`related:`、`site:`，则该任务费用乘以 `5`。不支持 `cache:` 的查询，提交后会返回校验错误。
`priority`	integer	可选。任务优级。`1` = 普通优级（默认），`2` = 高优级。高优级会额外计费。
`depth`	integer	可选。SERP 解析深度，即返回结果数量。默认值：`10`；最大值：`700`。计费按每个最多 `10` 条结果的 SERP 分段计算，因此 `10` 可能增加费用。若设置值高于返回结果数，差额自动退回。
`language_name`	string	可选。当未指定 `language_code` 时填。搜索引擎语言名；指定后可不传 `language_code`。可通过 `/v3/serp/haosou/languages` 获取可用语言列表。示例：`English`
`language_code`	string	可选。当未指定 `language_name` 时填。搜索引擎语言代码；指定后可不传 `language_name`。可通过 `/v3/serp/haosou/languages` 获取可用语言列表。示例：`en`
`device`	string	可选。设备类型：`desktop`、`mobile`。默认值：`desktop`
`os`	string	可选。设备操作系统。若 `device=desktop`，可选：`windows`、`macos`，默认 `windows`；若 `device=mobile`，可选：`android`、`ios`，默认 `android`
`calculate_rectangles`	boolean	可选。是否在高级结果中返回像素排名信息。像素排名表示结果摘要相对 SERP 页面顶部的距离。默认值：`false`。若设为 `true`，任务费用乘以 `2`
`browser_screen_width`	integer	可选。用于计算像素排名的浏览器屏幕宽度。默认值：桌面端 `1920`；Android 移动端 `360`；iOS 移动端 `375`。使用前提： `calculate_rectangles=true`
`browser_screen_height`	integer	可选。用于计算像素排名的浏览器屏幕高度。默认值：桌面端 `1080`；Android 移动端 `640`；iOS 移动端 `812`。使用前提： `calculate_rectangles=true`
`browser_screen_resolution_ratio`	integer	可选。用于计算像素排名的屏幕分辨率比例。默认值：桌面端 `1`；Android 移动端 `3`；iOS 移动端 `3`。使用前提： `calculate_rectangles=true`
`search_param`	string	可选。附加搜索参数，可用于限定搜索条件。例如使用 `&adv_t=d` 获取最近一天的结果。
`tag`	string	可选。自定义任务标识，最大长度 `255`。可用于在后续结果中业务侧任务。返回结果中的 `data` 数组会保留该值。
`postback_url`	string	可选。任务完成后，系统将结果以 gzip 压缩的 POST 请求发送到该地址。支持在 URL 中使用 `$id` 作为任务 ID 变量、`$tag` 作为经过 URL 编码的 tag 变量。例如：`http://your-server.com/postbackscript?id=$id` 或 `http://your-server.com/postbackscript?id=$id&tag=$tag`
`postback_data`	string	当指定 `postback_url` 时填。指定推送到您服务器的数据类型。可选值：`regular`、`advanced`、`html`
`pingback_url`	string	可选。任务完成后，系统会向该地址发送 GET 通知。支持 `$id` 和 `$tag` 变量。例如：`http://your-server.com/pingscript?id=$id` 或 `http://your-server.com/pingscript?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"
}

# 请求体为 JSON 数组
data = [
 {
 "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=data)
print(response.json)

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 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({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/haosou/organic/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	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	处理耗时，单位秒
`cost`	float	单个任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	URL 路径
`data`	array	与提交请求时传的参数基本一致
`result`	array	结果数组；对于 `task_post` 请求，此处通常为 `null`

建议为 status_code、任务级错误、网络异常和回调时建立完整的错误处理机制。完整错误码请参考 /v3/appendix/errors。

响应示例

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-5107d0b3aeab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0068 sec.",
 "cost": 0.00075,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "haosou",
 "organic",
 "task_post"
 ],
 "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": [
 "v3",
 "serp",
 "haosou",
 "organic",
 "task_post"
 ],
 "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
 }
 ]
}

常见状态与错误处理

通用状态码

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

处理建议

提交前校验 keyword 是否不支持的 cache:
批量提交时将单次任务数控制在 100
需要异步接收结果时，优使用 pingback_url 或 postback_url
若使用 postback_url，确保服务器能在 10 秒响应
对返回的 status_code、tasks_error 和每个 task 的 status_code 分别处理

实用场景

批量采集排名：按语言批量提交 Haosou 自然搜索任务，快速建立排名监控数据源。
对比桌面与移动端结果：分别设置 device 和 os，分析不同终端下的自然结果差异，移动端 SEO 优化。
监控时效性搜索结果：结合 search_param（如最近一天）抓取时效性结果，评估新闻、活动页或热点的表现。
分析结果首屏可见性：开启 calculate_rectangles 并设置屏幕参数，计算像素排名，判断目标页面是否处于首屏，提高点击率分析精度。
构建异步采集流水线：通过 pingback_url 或 postback_url 在任务完成后自动回传结果，减少轮询成本，提升大规模 SERP 采集效率。

提交 Haosou 自然搜索 SERP 任务 ​

接口地址 ​

计费说明 ​

请求说明 ​

频率与批量限制 ​

结果获取方式 ​

回调时说明 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks 数组字段 ​

响应示例 ​

常见状态与错误处理 ​

通用状态码 ​

处理建议 ​

实用场景 ​