获取 Google AI Mode 实时 SERP HTML

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

接口说明

该接口用于实时获取指定关键词、搜索引擎与地理位置下的 SERP 原始 HTML 页面数据。接口返回抓取到的 HTML，可用于页面结构分析、结果块识别、排名验证与页面归档。

• 请求方式：POST
• 接口地址：https://api.seermartech.cn/v3/serp/wp/v2/live/html

说明：原始文档标题为 Google AI Mode，但当前参考文档示例中的容路径为 /v3/serp/wp/v2/live/html。对接时请以可用路径为准，并保留 /v3/... 容路径不变。

计费说明

每次请求都会产生费用。

• 参考价约 ¥0.0480 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求规则

• 所有 POST 数据使用 JSON（UTF-8 编码）
• 请求体格式为 JSON 数组：[{ ... }]
• 实时接口每次调用支持 1 个任务
• 接口频率上限为 每分钟最多 2000 次 API 调用

---

请求参数

任务级参数

字段名	类型	说明
keyword	string	填。，最长支持 700 个字符。 %## 会被解码，+ 会被解码为空格。如需传递 %，请写为 %25；如需传递 +，请写为 %2B。
location_name	string	搜索位置完整名称。当未提供 location_code 或 location_coordinate 时填。使用该字段时，无需再传 location_code 或 location_coordinate。示例：London,England,United Kingdom
location_code	integer	搜索位置编码。当未提供 location_name 或 location_coordinate 时填。使用该字段时，无需再传 location_name 或 location_coordinate。示例：2840
location_coordinate	string	GPS 坐标位置。当未提供 location_name 或 location_code 时填。格式：latitude,longitude,radius。latitude 与 longitude 最多 7 位小数；radius 最小值为 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 对象中。

位置与语言接口

如需查询可用地域或语言，可使用以下容路径：

• 地域列表：/v3/serp/wp/locations
• 语言列表：/v3/serp/google/ai_mode/languages

---

响应结构

接口返回 JSON 编码结果，顶层 tasks 数组。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	局状态码，完整错误码见 /v3/appendix/errors
status_message	string	局状态信息，完整说明见 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
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	object	回显请求中提交的参数
result	array	结果数组

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
items_count	integer	items 数组中的结果数量
items	array	SERP 中解析出的结果项
page	integer	返回的 HTML 页序号
date	string	HTML 页面抓取时间，格式：year-month-date hours:minutes:seconds UTC_difference_hours:UTC_difference_minutes
html	string	原始 HTML 页面

---

请求示例

cURL

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"
 }
]'

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"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript

import axios from "axios";

async function fetchLiveHtml {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/wp/v2/live/html",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein",
 },
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 console.log(response.data);
}

fetchLiveHtml.catch(console.error);

---

响应示例

{
 "version": "0.1.20200130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "7.7543 sec.",
 "cost": 0.003,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "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": []
 }
 ]
}

---

状态码与错误处理

• 顶层 status_code=20000 通常表示请求成功
• 任务级 status_code 用于判断单个任务执行结果
• 完整错误码及状态说明请参考：/v3/appendix/errors

建议在接时同时处理以下：

1. HTTP 请求成功但业务状态码非成功
2. 顶层成功但 tasks_error > 0
3. tasks 返回为空或 result_count = 0
4. 参数缺失、语言/位置无效、额度不足、频率限等异常

---

使用说明与注意事项

• 本接口返回的是 原始 HTML，适合做页面结构抓取与结果验证，不等同于标准化字段解析接口
• 若需稳定提取自然结果、问题模块或 SERP素，建议结合解析型 SERP 接口使用
• keyword 中的特殊字符会被自动解码，构造请求时请注意 % 和 + 的转义规则
• 同一请求只提交一个任务对象，即 JSON 数组中一个

实用场景

• 抓取 指定在目标地区与语言下的原始 SERP 页面，用于复核真实搜索结果展示样式与布局变化
• 监控 AI Mode 或搜索结果页 HTML 结构变动，及时发现页面模块改版对解析规则的影响
• 校验 SEO 排名采集结果与展示页是否一致，降低解析偏差带来的监控误报
• 归档 重点在不同时间点的 SERP HTML 快，支持竞品分析、页面回溯与异常排查
• 训练 自定义页面解析器或特征提取程序，为 SERP 模块识别、富结果识别和数据洗提供原始样本