获取 Haosou 自然搜索 HTML 结果

接口说明

通过任务 id 获取 Haosou 自然搜索结果页的原始 HTML。

请求方式： GET请求地址： /v3/serp/haosou/organic/task_get/html/$id

说明：

• 账户在创建任务时扣费；
• 任务结果在生成后的 7 天可反复获取；
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

---

路径参数

字段	类型	说明
id	string	任务唯一标识符，UUID 格式。在任务创建后，可在 7 天使用该 id 随时获取结果。

---

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段	类型	说明
version	string	当前 API 版本号
status_code	integer	接口通用状态码，完整列表见 /v3/appendix/errors
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，完整列表见 /v3/appendix/errors
status_message	string	任务信息说明
time	string	任务执行时间，单位秒
cost	float	任务成本，单位 USD
result_count	integer	result 数组中的结果数量
path	array	当前请求的 URL 路径
data	array	与创建任务时 POST 请求中传的参数一致
result	array	结果数组

result[] 字段

字段	类型	说明
keyword	string	创建任务时的。返回时会对 %## 进行解码，+ 会被解码为空格。
type	string	POST 请求中指定的搜索类型
se_domain	string	POST 请求中指定的搜索引擎域名
location_code	integer	该字段固定为 0，因为 Haosou 会忽略地区参数
language_code	string	POST 请求中指定的语言代码
datetime	string	获取结果的时间，格式如：2019-11-15 12:57:46 +00:00
items_count	integer	items 数组中的结果数
items	array	搜索结果项数组

items[] 字段

字段	类型	说明
page	integer	返回的 HTML 页码序号
date	string	抓取该 HTML 页面的时间，格式如：2019-11-15 12:57:46 +00:00
html	string	搜索结果页原始 HTML

---

调用方式

cURL

id="02261816-2027-0066-0000-c27d02864073"

curl --location --request GET "https://api.seermartech.cn/v3/serp/haosou/organic/task_get/html/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

task_id = "02201650-1073-0066-2000-1d132bb28897"

url = f"https://api.seermartech.cn/v3/serp/haosou/organic/task_get/html/{task_id}"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json)

TypeScript

import axios from "axios";

const taskId = "02201650-1073-0066-2000-1d132bb28897";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/haosou/organic/task_get/html/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 结果数据
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

---

获取结果的推荐流程

通常建议按以下步骤获取结果：

1. 通过 /v3/serp/haosou/organic/tasks_ready 获取已完成任务列表；
2. 再根据返回的任务 id 或 endpoint_html 拉取 HTML 结果；
3. 对 tasks[].status_code、tasks[].result 做异常判断。

Python 示例：查已完成任务，再取 HTML

import requests

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

# 1. 获取已完成任务
ready_url = "https://api.seermartech.cn/v3/serp/haosou/organic/tasks_ready"
ready_response = requests.get(ready_url, headers=headers).json

results = []

if ready_response.get("status_code") == 20000:
 for task_group in ready_response.get("tasks", []):
 for task_info in task_group.get("result", []) or []:
 # 2. 通过 endpoint_html 获取结果
 endpoint_html = task_info.get("endpoint_html")
 if endpoint_html:
 full_url = f"https://api.seermartech.cn{endpoint_html}"
 task_result = requests.get(full_url, headers=headers).json
 results.append(task_result)

 # 3. 或直接通过任务 id 获取
 # task_id = task_info.get("id")
 # if task_id:
 # full_url = f"https://api.seermartech.cn/v3/serp/haosou/organic/task_get/html/{task_id}"
 # task_result = requests.get(full_url, headers=headers).json
 # results.append(task_result)

print(results)

TypeScript 示例：查已完成任务，再取 HTML

import axios from "axios";

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

async function getCompletedHaosouHtmlResults {
 const tasksResponses: any[] = [];

 const readyResponse = await axios.get(
 "https://api.seermartech.cn/v3/serp/haosou/organic/tasks_ready",
 { headers }
 );

 const tasksInfo = readyResponse.data;

 if (tasksInfo.status_code === 20000 && tasksInfo.tasks) {
 for (const taskGroup of tasksInfo.tasks) {
 if (taskGroup.result) {
 for (const task of taskGroup.result) {
 if (task.endpoint_html) {
 const taskGetResponse = await axios.get(
 `https://api.seermartech.cn${task.endpoint_html}`,
 { headers }
 );

 const taskResultObj = taskGetResponse.data;
 const firstTask = taskResultObj.tasks?.[0];

 if (!firstTask || firstTask.status_code >= 40000 || !firstTask.result) {
 console.error(
 `error. Code: ${firstTask?.status_code} Message: ${firstTask?.status_message}`
 );
 } else {
 tasksResponses.push(firstTask.result);
 }

 // 也可以直接按任务 id 获取
 /*
 const taskGetByIdResponse = await axios.get(
 `https://api.seermartech.cn/v3/serp/haosou/organic/task_get/html/${task.id}`,
 { headers }
 );
 */
 }
 }
 }
 }
 } else {
 console.error(
 `error. Code: ${tasksInfo.status_code} Message: ${tasksInfo.status_message}`
 );
 }

 if (tasksResponses.length > 0) {
 console.log(tasksResponses);
 } else {
 console.log("No completed tasks");
 }
}

getCompletedHaosouHtmlResults.catch(console.error);

---

响应示例

{
 "version": "0.1.20210105",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0966 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "haosou",
 "se_type": "organic",
 "keyword": "marketing",
 "language_code": "en",
 "priority": 2,
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 }
 ]
 }
 ]
}

---

状态码与异常处理

建议同时处理两层状态：

1. 顶层状态：status_code

• 20000 表示请求成功；
• 状态请参考 /v3/appendix/errors。

2. 任务层状态：tasks[].status_code

• 若大于等于 40000，通常表示任务级错误；
• 若 result 为空，也应按异常结果处理。

建议在生产环境中建立完善的错误重试、日志记录与空结果底逻辑。

---

注意事项

• 本接口返回的是 SERP 原始 HTML，适用于自定义解析或页面结构排查。
• Haosou 搜索结果中，location_code 始终为 0，因为该搜索引擎会忽略地区参数。
• 结果可在任务完成后的 7 天重复获取。
• keyword 字段会返回解码后的，例如 + 会转为空格。

实用场景

• 抓取原始页面结构：获取 Haosou 自然搜索结果页 HTML，用于自建解析器、DOM 提取器或页面结构研究。
• 排查解析异常：当标准化结果字段不足以定位问题时，直接查看 HTML 可帮助快速识别页面改版、反爬干扰或结构变更。
• 回放历史 SERP 页面：基于已完成任务在 7 天重复拉取 HTML，便于复核排名截图、页面证据和数据差异。
• 提取自定义：针对标题、摘要、跳转链接、站点附加信息等尚未标准化输出的进行二次解析。
• 验证投放环境：结合、语言和设备参数，检查特定查询下的真实结果页展示形态，为 SEO 策略提供依据。