获取好搜自然搜索结果 HTML

接口说明

GET /v3/serp/haosou/organic/task_get/html/$id

根据任务 ID 获取好搜（Haosou）自然搜索结果的原始 HTML。任务提交成功后，可在 7 天重复获取结果，获取任务结果不额外收费；费用在提交任务时产生。

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

请求参数

任务 ID 通过 URL 路径传递。

参数	类型	说明
`id`	string	任务唯一标识符，UUID 格式。任务提交后可在 7 天使用该 ID 获取任务结果。

请求示例

bash

curl --location --request GET \
  "https://api.seermartech.cn/v3/serp/haosou/organic/task_get/html/02261816-2027-0066-0000-c27d02864073" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

返回结果

接口返回 JSON 数据 tasks 数组。

顶层字段

字段	类型	说明
`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` 数组中的结果数量。
`path`	array	请求 URL 路径信息。
`data`	array	提交任务时使用的参数。
`result`	array	搜索结果数据数组。

`result` 数组中的字段

字段	类型	说明
`keyword`	string	提交任务时使用的。返回时会对经过 URL 编码的进行解码，`+` 会被解码为空格。
`type`	string	提交任务时使用的搜索类型。
`se_domain`	string	提交任务时使用的搜索引擎域名。
`location_code`	integer	地理位置编码。好搜会忽略地理位置，因此该值始终为 `0`。
`language_code`	string	语言编码。
`datetime`	string	获取搜索结果的日期和时间。格式为 `年-月-日时:分:秒 UTC 时差`，例如 `2019-11-15 12:57:46 +00:00`。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	SERP 中获取到的搜索结果。

`items` 数组中的字段

字段	类型	说明
`page`	integer	返回的 HTML 页面序号。
`date`	string	HTML 页面抓取日期和时间。格式为 `年-月-日时:分:秒 UTC 时差`，例如 `2019-11-15 12:57:46 +00:00`。
`html`	string	搜索结果 HTML 页面。

返回示例

json

{
  "version": "0.1.20210105",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0966 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02261816-2027-0066-0000-c27d02864073",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0800 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "haosou",
        "organic",
        "task_get",
        "html"
      ],
      "data": {
        "api": "serp",
        "function": "task_get",
        "se": "haosou",
        "se_type": "organic",
        "keyword": "marketing",
        "language_code": "en",
        "priority": 2,
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "marketing",
          "type": "organic",
          "se_domain": "haosou.com",
          "location_code": 0,
          "language_code": "en",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "items_count": 1,
          "items": [
            {
              "page": 1,
              "date": "2019-11-15 12:57:46 +00:00",
              "html": "<html>...</html>"
            }
          ]
        }
      ]
    }
  ]
}

错误处理

请同时检查以下状态字段：

顶层 status_code
任务级 tasks[].status_code
对应的 status_message

当任务级状态码表示失败，或 result 为空时，应记录错误信息并执行重试、告警或人工检查。完整状态码和错误信息请参错误码文档。

获取已完成任务后读取结果

如果使用任务就绪查询接口，可调用：

GET /v3/serp/haosou/organic/tasks_ready

然后使用返回的任务 ID 调用：

GET /v3/serp/haosou/organic/task_get/html/$id

Python 示例

python

import requests

api_key = "smt_live_YOUR_KEY"
task_id = "02261816-2027-0066-0000-c27d02864073"

url = (
    "https://api.seermartech.cn"
    "/v3/serp/haosou/organic/task_get/html/"
    + task_id
)

response = requests.get(
    url,
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
)

response.raise_for_status()
data = response.json()

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        "请求失败：",
        data.get("status_code"),
        data.get("status_message"),
    )

TypeScript 示例

typescript

import axios from "axios";

const taskId = "02261816-2027-0066-0000-c27d02864073";

axios
  .get(
    `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) => {
    // 处理返回的 HTML 和任务数据
    console.log(response.data);
  })
  .catch((error) => {
    if (error.response) {
      console.error(
        "请求失败：",
        error.response.data.status_code,
        error.response.data.status_message
      );
    } else {
      console.error("网络请求失败：", error.message);
    }
  });

PHP 示例

php

<?php

$taskId = '02261816-2027-0066-0000-c27d02864073';
$url = 'https://api.seermartech.cn/v3/serp/haosou/organic/task_get/html/' . $taskId;

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    die('请求失败：' . curl_error($ch));
}

curl_close($ch);

$data = json_decode($response, true);

if (($data['status_code'] ?? null) === 20000) {
    print_r($data);
} else {
    echo '请求失败：'
        . ($data['status_code'] ?? 'unknown')
        . ' '
        . ($data['status_message'] ?? '');
}

C# 示例

csharp

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class SerpTaskGetExample
{
    public static async Task Main()
    {
        var taskId = "02261816-2027-0066-0000-c27d02864073";

        using var client = new HttpClient();

        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue(
                "Bearer",
                "smt_live_YOUR_KEY"
            );

        var url =
            "https://api.seermartech.cn" +
            "/v3/serp/haosou/organic/task_get/html/" +
            taskId;

        var response = await client.GetAsync(url);
        var content = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            Console.WriteLine(content);
        }
        else
        {
            Console.WriteLine(
                $"HTTP 请求失败：{response.StatusCode}\n{content}"
            );
        }
    }
}

实用场景

抓取指定的好搜 SERP 原始 HTML，保留完整页面结构，支持后续自定义解析和排名监控。
构建排名采集系统，定期获取同一的 HTML 页面，分析自然结果位置变化。
验证搜索结果页面，检查标题、摘要、链接及 SERP 模块是否按预期展示。
开展竞品搜索结果研究，批量保存竞品在目标下的自然搜索页面。
复现历史搜索页面，在 7 天有效期重新获取任务结果，用于调试解析规则或核对数据。

获取好搜自然搜索结果 HTML ​

接口说明 ​

请求参数 ​

请求示例 ​

返回结果 ​

顶层字段 ​

tasks 数组中的任务字段 ​

result 数组中的字段 ​

items 数组中的字段 ​

返回示例 ​

错误处理 ​

获取已完成任务后读取结果 ​

Python 示例 ​

TypeScript 示例 ​

PHP 示例 ​

C# 示例 ​

实用场景 ​