Google AI Mode 实时 SERP HTML

POST /v3/serp/google/ai_mode/live/html

本接口使用 POST 方法，请求路径为：

/v3/serp/wp/v2/live/html

实时 SERP HTML 接口根据指定的、搜索引擎和地理位置，返回搜索结果页面的原始 HTML。平台限流以认证说明中的 30/60/120 次/分钟规则为准。

计费说明

每次成功提交请求都会产生费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有 POST 数据使用 UTF-8 编码的 JSON 格式，并以 JSON 数组提交：

json

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

请求参数

参数	类型	说明
`keyword`	string	查询。填。最多 700 个字符。接口会对 `%##` 编码进行解码，并将加号 `+` 解码为空格。如果中需要使用百分号 `%`，请编码为 `%25`；如果需要使用加号 `+`，请编码为 `%2B`。
`location_name`	string	搜索引擎地理位置的完整名称。当未指定 `location_code` 或 `location_coordinate` 时填。使用该参数后，无需再提交另外两个位置参数。可通过 `/v3/serp/wp/locations` 获取可用位置名称。示例：`London,England,United Kingdom`
`location_code`	integer	搜索引擎地理位置代码。当未指定 `location_name` 或 `location_coordinate` 时填。使用该参数后，无需再提交另外两个位置参数。可通过 `/v3/serp/wp/locations` 获取可用位置代码。示例：`2840`
`location_coordinate`	string	地理位置 GPS 坐标。当未指定 `location_name` 或 `location_code` 时填。格式为 `纬度,经度,半径`。纬度和经度最多支持 7 位小数；半径最小值为 `199.9` 米，最大值为 `199999` 米。示例：`53.476225,-2.243572,200`
`language_name`	string	搜索引擎语言的完整名称。当未指定 `language_code` 时填。使用该参数后，无需再提交 `language_code`。可通过 `/v3/serp/google/ai_mode/languages` 获取可用语言名称。
`language_code`	string	搜索引擎语言代码。当未指定 `language_name` 时填。使用该参数后，无需再提交 `language_name`。可通过 `/v3/serp/google/ai_mode/languages` 获取可用语言代码。
`device`	string	设备类型，可选值为 `desktop` 或 `mobile`。默认值为 `desktop`。
`os`	string	设备操作系统。当 `device` 为 `desktop` 时，可选值为 `windows`、`macos`，默认值为 `windows`；当 `device` 为 `mobile` 时，可选值为 `android`、`ios`，默认值为 `android`。
`tag`	string	自定义任务标识，可选，最多 255 个字符。可用于识别任务并与响应结果进行匹。提交的值会原样返回在响应的 `data` 对象中。

> location_name、location_code 和 location_coordinate 三只能选择一个。
> language_name 和 language_code 二只能选择一个。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/wp/v2/live/html" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "keyword": "albert einstein",
      "device": "desktop",
      "os": "windows",
      "tag": "tag2"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/live/html"

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

# 每次请求只能提交一个任务
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
        "device": "desktop",
        "os": "windows",
        "tag": "tag2",
    }
]

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 response = await axios.post(
  "https://api.seermartech.cn/v3/serp/wp/v2/live/html",
  [
    {
      language_code: "en",
      location_code: 2840,
      keyword: "albert einstein",
      device: "desktop",
      os: "windows",
      tag: "tag2",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

const result = response.data;

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(
    `请求失败，状态码：${result.status_code}，信息：${result.status_message}`
  );
}

响应结构

接口返回 JSON 对象 tasks 数组。每个任务对应一个提交的请求。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	顶层响应状态码。`20000` 表示请求成功。完整状态码列表请参考错误码文档。
`status_message`	string	顶层响应说明。
`time`	string	请求执行耗时，例如 `7.7543 sec.`。
`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`	object	请求中提交的任务参数。
`result`	array	SERP 结果数组。

`result` 结果字段

字段	类型	说明
`keyword`	string	请求中的。返回时已对 `%##` 编码进行解码，加号 `+` 会被解码为空格。
`type`	string	请求中的搜索引擎类型。
`se_domain`	string	请求中的搜索引擎域名。
`location_code`	integer	地理位置代码。
`language_code`	string	语言代码。
`datetime`	string	获取结果的日期和时间，使用 UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。示例：`2019-11-15 12:57:46 +00:00`。
`items_count`	integer	`items` 数组中返回的结果数量。
`items`	array	SERP 中识别到的搜索结果。
`page`	integer	返回的 HTML 页面序号。
`date`	string	HTML 页面扫描时间，格式为 `年-月-日时:分:秒 UTC 时差`。示例：`2019-11-15 12:57:46 +00:00`。
`html`	string	搜索结果页面的原始 HTML。

响应示例

json

{
  "version": "0.1.20200130",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "7.7543 sec.",
  "cost": 0.003,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "12345678-1234-1234-1234-123456789012",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "7.5000 sec.",
      "cost": 0.003,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "wp",
        "v2",
        "live",
        "html"
      ],
      "data": {
        "api": "serp",
        "function": "live",
        "se": "wp",
        "se_type": "v2",
        "language_code": "en",
        "location_code": "2840",
        "keyword": "albert einstein",
        "tag": "tag2",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "albert einstein",
          "type": "v2",
          "se_domain": "google.com",
          "location_code": 2840,
          "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 是否为 20000。
检查 tasks_error 是否大于 0。
逐项检查 tasks[].status_code 和 tasks[].status_message。
对网络时、鉴权失败、参数缺失和平台搜索请求异常进行重试或记录。

实用场景

采集指定的原始 SERP HTML，还原搜索结果页面结构，为自建解析器、页面渲染和结果抽取流程提供原始数据。
对比不同国家、城市和语言下的搜索页面，识别本地化 SERP 差异，支持 SEO 和区域策略制定。
分别抓取桌面端与移动端结果页面，分析设备差异对搜索展现的影响，移动端 SEO 优化。
按任务标签追踪批量采集结果，将 HTML 页面与、项目或客户，提升 SEO 监测任务的可追溯性。
定期保存搜索页面快，对比不同时间点的 SERP 变化，为竞争对手监控、排名波动分析和搜索功能研究提供依据。

Google AI Mode 实时 SERP HTML ​

计费说明 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

tasks 任务字段 ​

result 结果字段 ​

响应示例 ​

错误处理 ​

实用场景 ​