SeerMarTech API 文档

主题

按任务 ID 获取好搜自然搜索结果（高级版） ​

接口说明 ​

GET https://api.seermartech.cn/v3/serp/haosou/organic/task_get/advanced/$id

本接口根据任务 ID 获取好搜（Haosou）自然搜索结果的高级数据。任务提交成功后，可在 30 天重复获取任务结果；系统对任务提交操作计费。

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

请求参数 ​

请求无需请求体，任务 ID 通过 URL 路径传递。

参数类型说明
idstring任务唯一标识，UUID 格式。任务提交后 30 天可使用该 ID 获取结果。

请求示例 ​

cURL ​

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

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

Python ​

python
import requests

task_id = "02231256-2604-0066-2000-57133b8fc54e"

response = requests.get(
    f"https://api.seermartech.cn/v3/serp/haosou/organic/task_get/advanced/{task_id}",
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
)

data = response.json()
print(data)

TypeScript ​

typescript
import axios from "axios";

const taskId = "02231256-2604-0066-2000-57133b8fc54e";

axios
  .get(
    `https://api.seermartech.cn/v3/serp/haosou/organic/task_get/advanced/${taskId}`,
    {
      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 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求级状态码。
status_messagestring请求级状态说明。
timestring接口执行耗时，例如 0.0819 sec.。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务结果数组。

任务对象字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常在 10000 至 60000 范围。
status_messagestring任务状态说明。
timestring任务执行耗时。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的结果数量。
patharray请求路径信息。
dataarray/object创建任务时提交的参数。
resultarraySERP 结果数组。

result 字段 ​

字段类型说明
keywordstring请求中的。返回值会对 URL 编码进行解码，+ 会被解码为空格。
typestring请求中的搜索类型，例如 organic。
se_domainstring搜索引擎域名。
location_codeinteger地区代码。好搜会忽略地区设置，因此该值固定为 0。
language_codestring请求中的语言代码。
check_urlstring直接访问搜索结果页的 URL，可用于人工核验结果准确性。
datetimestring获取结果的日期和时间，格式为 YYYY-MM-DD HH:mm:ss ±UTC偏移，例如 2019-11-15 12:57:46 +00:00。
spellarray搜索引擎自动纠错信息。
item_typesarray当前 SERP 中出现的结果类型。可能 local_pack、map、organic、paid、related_searches、video、images。
se_results_countintegerSERP 中的结果总数。
items_countintegeritems 数组中的结果数量。
itemsarraySERP 结果数组。

spell 自动纠错字段 ​

字段类型说明
keywordstring搜索引擎自动纠正后的，结果该返回。
typestring纠错类型。可选值：did_you_mean、showing_results_for、no_results_found_for。

SERP 通用字段 ​

以下字段适用于多种 SERP素：

字段类型说明
typestringSERP素类型。
rank_groupinteger同类型中的分组排名。不同类型之间不计该排名。
rank_absoluteinteger在 SERP素中的绝对排名。
positionstring素在页面中的对齐位置，可为 left 或 right。
xpathstringSERP素对应的 XPath。
rectanglearray/null素在 SERP 中的坐标和尺寸。当提交任务时未将 calculate_rectangles 设置为 true 时为 null。

rectangle 字段 ​

字段类型说明
xinteger素左上角的横坐标。
yinteger素左上角的纵坐标。
widthinteger素宽度，单位为像素。
heightinteger素高度，单位为像素。

坐标原点为 SERP 页面左上角。

自然结果 organic ​

当 type 为 organic 时，结果对象还以下字段：

字段类型说明
domainstring搜索结果域名。
titlestring搜索结果标题。
urlstring搜索结果 URL。
cache_urlstring/null页面缓存 URL。
breadcrumbstring搜索结果面屑路径。
is_imageboolean是否图片。
is_videoboolean是否视频。
is_featured_snippetboolean是否为精选摘要。
is_maliciousboolean是否被标记为恶意结果。
is_web_storyboolean是否为 Web Story。
descriptionstringSERP 中展示的结果描述。
pre_snippetstring/null展示在结果描述前的附加信息。
extended_snippetstring/null展示在结果描述后的附加信息。
amp_versionboolean是否存在 AMP（加速移动页面）版本。
ratingarray/null结果评分信息。
highlightedarray/null结果描述中以粗体突出显示的词语。
linksarray/null站点链接。无站点链接时为 null。
faqarray/nullFAQ 问答扩展。无 FAQ 时为 null。
timestampstring/null结果发布时间，格式为 YYYY-MM-DD HH:mm:ss ±UTC偏移。
rectanglearray/null结果的页面坐标和尺寸。

rating 评分字段 ​

字段类型说明
rating_typestring评分类型，可为 Max5、Percents 或 CustomMax。
valueinteger评分值。
votes_countinteger评价数量。
rating_maxinteger当前评分类型的最大值。
字段类型说明
typestring固定为 link_element。
titlestring链接标题。
descriptionstring链接描述。
urlstring站点链接 URL。

faq FAQ 字段 ​

faq 通常一个或多个 FAQ 容器：

字段类型说明
typestring固定为 faq_box。
itemsarrayFAQ 条目数组。

FAQ 条目字段：

字段类型说明
typestring固定为 faq_box_element。
titlestring问题标题。
descriptionstring下拉区域中的答案。
linksarray/nullFAQ 条目中的链接。

FAQ 链接字段：

字段类型说明
typestring固定为 link_element。
titlestring链接锚文本。
urlstring链接 URL。

付费结果 paid ​

当 type 为 paid 时，结果对象以下字段：

字段类型说明
domainstring广告结果域名。
descriptionstring广告描述。
titlestring广告标题。
urlstring广告目标 URL。
breadcrumbstring/null广告结果面屑路径。
highlightedarray/null描述中突出显示的词语。
extraarray/object/null广告附加信息。
description_rowsarray/null扩展描述信息。
linksarray/null广告站点链接。
ad_aclkstring/null广告标识。
rectanglearray/null广告的页面坐标和尺寸。

付费结果中的 links 使用以下字段：

字段类型说明
typestring固定为 link_element。
titlestring链接标题。
descriptionstring链接描述。
urlstring链接 URL。
ad_aclkstring/null链接对应的广告标识。
字段类型说明
typestring固定为 related_searches。
rank_groupinteger同类型中的分组排名。
rank_absoluteinteger在 SERP素中的绝对排名。
positionstring对齐位置，可为 left 或 right。
xpathstring素 XPath。
itemsarray/null搜索条目。
rectanglearray/null素坐标和尺寸。

本地结果 local_pack ​

字段类型说明
typestring固定为 local_pack。
titlestring本地商户或地点名称。
descriptionstring本地结果描述。
domainstring/null商户域名。
phonestring/null电话号码。
urlstring/nullURL。
is_paidboolean是否为广告结果。
ratingarray/null商户评分，字段结构同 rating。
cidstring/null本地商户唯一客户端 ID。
rectanglearray/null素坐标和尺寸。

地图结果 map ​

字段类型说明
typestring固定为 map。
rank_groupinteger同类型中的分组排名。
rank_absoluteinteger在 SERP素中的绝对排名。
positionstring对齐位置，可为 left 或 right。
xpathstring素 XPath。
titlestring地图结果标题。
urlstring地图结果 URL。
rectanglearray/null素坐标和尺寸。

视频结果 video ​

字段类型说明
typestring固定为 video。
rank_groupinteger同类型中的分组排名。
rank_absoluteinteger在 SERP素中的绝对排名。
positionstring对齐位置，可为 left 或 right。
xpathstring素 XPath。
itemsarray/null视频条目数组。
rectanglearray/null素坐标和尺寸。

视频条目字段：

字段类型说明
typestring固定为 video_element。
sourcestring视频来源。
titlestring视频标题。
timestampstring/null视频发布时间。
urlstring视频 URL。
rectanglearray/null视频条目的坐标和尺寸。

图片结果 images ​

字段类型说明
typestring固定为 images。
rank_groupinteger同类型中的分组排名。
rank_absoluteinteger在 SERP素中的绝对排名。
positionstring对齐位置，可为 left 或 right。
xpathstring素 XPath。
titlestring图片结果标题。
urlstring图片结果页面 URL。
itemsarray/null图片条目数组。
rectanglearray/null素坐标和尺寸。

图片条目字段：

字段类型说明
typestring固定为 images_element。
altstring图片替代文本。
urlstring图片 URL。该 URL 可能指向原始资源，也可能指向本平台存储的图片资源。
rectanglearray/null图片条目的坐标和尺寸。

响应示例 ​

json
{
  "version": "0.1.20210105",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0819 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02261816-2027-0066-0000-c27d02864073",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0700 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "haosou",
        "organic",
        "task_get",
        "advanced"
      ],
      "data": {
        "api": "serp",
        "function": "task_get",
        "se": "haosou",
        "se_type": "organic",
        "keyword": "marketing",
        "language_code": "zh_CN",
        "priority": 2,
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "marketing",
          "type": "organic",
          "se_domain": "so.com",
          "location_code": 0,
          "language_code": "zh_CN",
          "check_url": "https://www.so.com/s?q=marketing",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "spell": null,
          "item_types": [
            "organic",
            "paid",
            "images",
            "video",
            "map",
            "related_searches",
            "local_pack"
          ],
          "se_results_count": 1240000,
          "items_count": 10,
          "items": [
            {
              "type": "organic",
              "rank_group": 1,
              "rank_absolute": 1,
              "position": "left",
              "xpath": "/html/body/div/div/div/ul/li",
              "domain": "www.example.com",
              "title": "示例搜索结果",
              "url": "https://www.example.com/page",
              "cache_url": null,
              "breadcrumb": "www.example.com/page",
              "is_image": false,
              "is_video": false,
              "is_featured_snippet": false,
              "is_malicious": false,
              "is_web_story": false,
              "description": "搜索结果描述。",
              "pre_snippet": null,
              "extended_snippet": null,
              "amp_version": false,
              "rating": null,
              "highlighted": [],
              "links": null,
              "faq": null,
              "timestamp": null,
              "rectangle": null
            },
            {
              "type": "paid",
              "rank_group": 1,
              "rank_absolute": 2,
              "position": "left",
              "xpath": "/html/body/div/div/div/ul/li/div",
              "domain": "ads.example.com",
              "description": "广告描述。",
              "title": "广告标题",
              "url": "https://ads.example.com/landing",
              "breadcrumb": null,
              "highlighted": null,
              "extra": {
                "ad_aclk": null
              },
              "description_rows": null,
              "links": null,
              "ad_aclk": null,
              "rectangle": null
            },
            {
              "type": "images",
              "rank_group": 1,
              "rank_absolute": 3,
              "position": "left",
              "xpath": "/html/body/div/div/div/ul/li",
              "title": "图片搜索结果",
              "url": "https://image.example.com/search?q=marketing",
              "items": [],
              "rectangle": null
            },
            {
              "type": "video",
              "rank_group": 1,
              "rank_absolute": 4,
              "position": "left",
              "xpath": "/html/body/div/div/div/ul/li/div",
              "items": [],
              "rectangle": null
            },
            {
              "type": "map",
              "rank_group": 1,
              "rank_absolute": 5,
              "position": "left",
              "xpath": "/html/body/div/div/div/ul/li/div",
              "title": "地图结果",
              "url": "https://map.example.com/",
              "rectangle": null
            },
            {
              "type": "related_searches",
              "rank_group": 1,
              "rank_absolute": 6,
              "position": "left",
              "xpath": "/html/body/div/div/div/div/dl",
              "items": [],
              "rectangle": null
            },
            {
              "type": "local_pack",
              "rank_group": 1,
              "rank_absolute": 7,
              "position": "left",
              "xpath": "/html/body/div/div/div/ul/li/div",
              "title": "示例本地商户",
              "description": "商户地址及简介。",
              "domain": null,
              "phone": null,
              "url": null,
              "is_paid": false,
              "rating": null,
              "cid": null,
              "rectangle": null
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理 ​

建议根据以下字段实现异常处理：

  • 首检查顶层 status_code。
  • 再检查每个任务对象中的 status_code。
  • 当任务状态码表示失败，或 result 为 null 时，应读取 status_message 并记录错误。
  • tasks_error 可用于统计本次响应中失败的任务数量。
  • 业务系统应对任务不存在、任务尚未完成、任务已过期及参数错误等进行重试或告警处理。

实用场景 ​

  • 监测自然排名：获取好搜 SERP 中的自然结果、绝对排名和分组排名，评估网站在目标上的可见度变化。
  • 分析 SERP 特征占位：识别自然结果、付费广告、图片、视频、地图、本地结果和搜索等，指导与页面结构优化。
  • 核验搜索结果准确性：结合 check_url、datetime 和 xpath 对搜索页面进行抽样复核，提升排名监控数据的可信度。
  • 评估竞争对手搜索表现：提取竞争页面的域名、标题、URL、描述和面屑信息，建立竞争结果库。
  • 优化本地 SEO 与广告策略：分析 local_pack、map 和 paid 结果中的商户、广告及排名信息，本地门店和搜索广告投放决策。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API