Google AI Mode 实时高级 SERP 接口

POST /v3/serp/google/ai_mode/live/advanced

接口概述

该接口用于获取 Google 搜索中 AI Mode 功能返回的高级搜索结果。相比普通结果，本接口会返回更结构化的 AI：

• AI Overview 主体

• 引用来源（references）

• 链接、图片、视频、表格、扩展模块

• 购物型 AI 概览

• 可选的像素坐标信息（rectangle）

• 请求方式：POST

• 接口地址：https://api.seermartech.cn/v3/serp/google/ai_mode/live/advanced

计费与调用限制

本接口按请求计费，每次请求都会扣费。

• 参考价约 ¥0.0640 / 次
• 如启用 calculate_rectangles=true，单次任务费用会 翻倍
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

调用限制说明：

• 每分钟最多可发送 2000 次 API 调用
• 每次 Live SERP 请求 只能 1 个任务
• POST 数据使用 JSON（UTF-8 编码）
• POST 请求体格式为 JSON 数组：[{ ... }]

---

请求参数

主要参数

字段名	类型	说明
keyword	string	填。搜索，最长 700 个字符。%## 会被解码，+ 会被解码为空格。如果中需要保留 %，请写为 %25；如需保留 +，请写为 %2B。
location_code	integer	当未提供 location_name 或 location_coordinate 时填。搜索地域编码。若使用该字段，则无需再传 location_name 或 location_coordinate。可通过 /v3/serp/google/locations 获取可用地区编码。注意：AI Mode 在部分国家/地区可用。
language_code	string	当未提供 language_name 时填。搜索语言编码。若使用该字段，则无需再传 language_name。可通过 /v3/serp/google/ai_mode/languages 获取可用语言编码。
device	string	可选。设备类型，可选值：desktop、mobile。默认值：desktop。

追加参数

字段名	类型	说明
location_name	string	当未提供 location_code 或 location_coordinate 时填。搜索地域完整名称。若使用该字段，则无需再传 location_code 或 location_coordinate。可通过 /v3/serp/google/locations 获取可用地区名称。
language_name	string	当未提供 language_code 时填。搜索语言完整名称。若使用该字段，则无需再传 language_code。可通过 /v3/serp/google/ai_mode/languages 获取可用语言名称。
os	string	可选。设备操作系统。若 device=desktop，可选：windows、macos，默认 windows；若 device=mobile，可选：android、ios，默认 android。
tag	string	可选。自定义任务标识，最长 255 个字符。便于将请求与响应结果对应。响应中的 data 对象会返回该值。
calculate_rectangles	boolean	可选。是否计算高级结果中 SERP素的像素位置。像素排名表示结果片段相对屏幕左上角的距离。默认 false。注意：设置为 true 后费用翻倍。
browser_screen_width	integer	可选。浏览器屏幕宽度，用于计算像素坐标。取值范围：240-9999。默认：桌面 1920，Android 移动端 360，iOS 移动端 375。使用该字段时需设置 calculate_rectangles=true。
browser_screen_height	integer	可选。浏览器屏幕高度，用于计算像素坐标。取值范围：240-9999。默认：桌面 1080，Android 移动端 640，iOS 移动端 812。使用该字段时需设置 calculate_rectangles=true。
browser_screen_resolution_ratio	integer	可选。屏幕分辨率比例，用于计算像素坐标。取值范围：0.5-3。默认：桌面 1，Android 3，iOS 3。使用该字段时需设置 calculate_rectangles=true。
location_coordinate	string	当未提供 location_name 或 location_code 时填。GPS 坐标，格式：latitude,longitude,zoom。若未传 zoom，默认使用 9z。纬度与经度最多支持 7 位小数；zoom 范围为 4z-18z。示例：52.6178549,-155.352142,18z

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/google/ai_mode/live/advanced" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "what is google ai mode"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/serp/google/ai_mode/live/advanced"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "what is google ai mode"
 }
]

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

TypeScript

import axios from "axios";

async function fetchAiModeSerp {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/google/ai_mode/live/advanced",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "what is google ai mode",
 },
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 // 输出结果数据
 console.log(response.data);
}

fetchAiModeSerp.catch(console.error);

---

响应结构

接口返回 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	array	任务数组。

任务对象字段

字段名	类型	说明
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	请求中的语言编码。
check_url	string	可直接打开的搜索结果地址，用于校验返回结果。
datetime	string	抓取结果时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
spell	object	搜索引擎自动纠错信息。若无则为 null。
refinement_chips	object	搜索细化建议。若无则为 null。
item_types	array	SERP 中出现的结果类型列表。当前可能：ai_overview。
se_results_count	integer	SERP 总结果数。
items_count	integer	items 数组中的数量。
items	array	SERP 中解析出的结果。

---

spell 字段说明

当搜索引擎对进行了自动纠错时，会返回该对象；否则为 null。

字段名	类型	说明
keyword	string	自动纠错后的。
type	string	纠错类型，可选值：did_you_mean、showing_results_for、no_results_found_for、including_results_for。

---

refinement_chips 字段说明

字段名	类型	说明
type	string	素类型，固定为 refinement_chips。
xpath	string	素的 XPath。
items	array	细化建议项。

refinement_chips.items 字段

字段名	类型	说明
type	string	素类型，固定为 refinement_chips_element。
title	string	建议标题。
url	string	带细化参数的搜索 URL。
domain	string	SERP 中的域名。
options	array	进一步细化选项。

refinement_chips.items.options 字段

字段名	类型	说明
type	string	素类型，固定为 refinement_chips_option。
title	string	选项标题。
url	string	带细化参数的搜索 URL。
domain	string	SERP 中的域名。

---

items 结果类型说明

1) ai_overview

AI Mode 返回的主要 AI 概览。

字段名	类型	说明
type	string	素类型，固定为 ai_overview。
rank_group	integer	同类型分组排名。
rank_absolute	integer	SERP部中的绝对排名。
page	integer	所在 SERP 页码。
position	string	在 SERP 中的位置，可选：left、right。
xpath	string	素 XPath。
markdown	string	AI Overview 的 Markdown 格式。
items	array	AI 概览中的子。
references	array	与该 AI 概览的附加引用来源。
rectangle	object	结果区域的像素坐标与尺寸；若未开启 calculate_rectangles，则为 null。

---

ai_overview.items 子类型

ai_overview_element

常规 AI 段落、标题、说明块。

字段名	类型	说明
type	string	固定为 ai_overview_element。
position	string	位置，可选：left、right。
title	string	素标题。
text	string	素文本或描述。
markdown	string	Markdown 格式。
links	array	素中的站点链接；无则为 null。
images	array	素中的图片；无则为 null。
references	array	与该的引用来源。

links 字段

字段名	类型	说明
type	string	固定为 link_element。
title	string	链接锚文本。
description	string	链接描述。
url	string	链接地址。
domain	string	链接域名。

images 字段

字段名	类型	说明
type	string	固定为 images_element。
alt	string	图片 alt 文本。
url	string	页面 URL。
image_url	string	图片 URL。若原图不可用，可能返回平台存储地址。

references 字段

字段名	类型	说明
type	string	固定为 ai_overview_reference。
source	string	引用来源名称或标题。
domain	string	引用来源域名。
url	string	引用页面 URL。
title	string	引用页面标题。
text	string	被用于生成 AI的文本片段。

---

ai_overview_video_element

AI 概览中的视频型块。

字段名	类型	说明
type	string	固定为 ai_overview_video_element。
position	string	位置，可选：left、right。
title	string	视频标题。
snippet	string	视频补说明。
url	string	视频链接地址。
domain	string	托管视频的网站域名。
image_url	string	视频缩略图地址。
source	string	视频来源名称。
date	string	视频发布时间或索引时间，例如 Apr 26, 2024。
timestamp	string	UTC 时间戳，格式：yyyy-mm-dd hh-mm-ss +00:00。

---

ai_overview_table_element

AI 概览中的表格型块。

字段名	类型	说明
type	string	固定为 ai_overview_table_element。
position	string	位置，可选：left、right。
markdown	string	表格的 Markdown 表示。
table	object	结构化表格数据。
references	array	与表格的引用来源。

table 字段

字段名	类型	说明
table_header	array	表头。
table_content	array	表格，每个数组代表一行。

---

ai_overview_expanded_element

AI 概览中的扩展块。

字段名	类型	说明
type	string	固定为 ai_overview_expanded_element。
position	string	位置，可选：left、right。
title	string	扩展块标题。
text	string	扩展块附加文本。
components	array	扩展块中的组件数组。

components 字段

字段名	类型	说明
type	array	组件类型，固定为 ai_overview_expanded_component。
title	string	组件标题。
text	string	组件文本。
markdown	string	组件的 Markdown 文本。
images	array	组件图片；无则为 null。
links	array	组件中的链接；无则为 null。

---

ai_overview_shopping

AI 概览中的购物结果块。

字段名	类型	说明
type	string	固定为 ai_overview_shopping。
position	string	位置，可选：left、right。
title	string	素标题。
markdown	string	Markdown 格式。
items	array	购物项列表。
references	array	与该购物块的附加引用来源。

ai_overview_shopping.items 字段

字段名	类型	说明
type	string	固定为 ai_overview_shopping_element。
product_id	string	Google Shopping 商品唯一标识。
data_docid	string	SERP 数据唯一标识。
gid	string	Google Shopping局商品标识。
title	string	商品标题。
url	string	带参数的搜索 URL。
domain	string	SERP 中显示的域名。
rating	object	商品评分对象；无则为 null。
price	object	商品价格对象；无则为 null。
seller	string	商品卖家名称。
snippet	string	结果补说明。
marketplace	string	商家账户提供方，例如 by Google。
marketplace_url	string	商家账户提供方 URL。
image_url	string	商品图片地址。
references	array	与该商品项的附加引用来源。

rating 字段

字段名	类型	说明
rating_type	string	评分类型，可为 Max5、Percents、CustomMax。
value	float	评分值。
votes_count	integer	评论或反馈数量。
rating_max	integer	当前评分体系下的最大值。

price 字段

字段名	类型	说明
current	float	当前价格。
regular	float	原价。
max_value	float	最高价格。
currency	string	币种，ISO 代码。
is_price_range	boolean	是否为价格区间。
displayed_price	string	搜索结果中展示的原始价格字符串。

---

rectangle 字段说明

当请求中设置 calculate_rectangles=true 时返回。

字段名	类型	说明
x	integer	左上角横坐标，以屏幕左上角为原点。
y	integer	左上角纵坐标，以屏幕左上角为原点。
width	integer	素宽度（像素）。
height	integer	素高度（像素）。

---

响应示例

{
 "version": "0.1.20260223",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "12.8697 sec.",
 "cost": 0.004,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "ai_mode",
 "language_name": "English",
 "location_name": "London,England,United Kingdom",
 "keyword": "iphone 16 price comparison",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 0,
 "items_count": 1,
 "items": [
 {
 "type": "ai_overview",
 "position": "left",
 "markdown": "AI 概览（示例已截断）",
 "items": [
 {
 "type": "ai_overview_element",
 "position": "left",
 "title": "UK Price Comparison by Model (SIM-Free)",
 "text": "Retail prices in the UK vary slightly between the official Apple Store and major electronics retailers.",
 "markdown": "Retail prices in the UK vary slightly between the official Apple Store and major electronics retailers.",
 "links": null,
 "images": null,
 "references": null
 },
 {
 "type": "ai_overview_table_element",
 "position": "left",
 "markdown": "| Model | 128GB | 256GB | 512GB | 1TB |",
 "table": {
 "table_header": null,
 "table_content": []
 }
 }
 ],
 "references": [],
 "rectangle": null
 }
 ]
 }
 ]
 }
 ]
}

---

错误处理

请根据以下字段判断请求与任务执行状态：

• 顶层 status_code / status_message
• 任务级 tasks[].status_code / tasks[].status_message

完整错误码与状态说明请参考：

• /v3/appendix/errors

建议在接时至少处理以下：

• 认证失败
• 参数缺失或格式错误
• 地区或语言不支持 AI Mode
• 请求频率限
• 搜索结果暂不可用
• 任务成功但结果为空

使用说明补

• Live 模式下每次请求支持一个任务
• 若需验证抓取结果是否与目标搜索页一致，可使用返回的 check_url
• 若需要定位 AI 模块在页面中的像素位置，请启用 calculate_rectangles
• 若传 location_code，无需再传 location_name 或 location_coordinate
• 若传 language_code，无需再传 language_name

实用场景

• 监控 AI 概览引用来源：抓取 AI Overview 中的 references，识别品牌是否被平台 AI 回答引用，用于评估影响力与品牌。
• 分析 AI 回答结构：解析 ai_overview_element、表格、视频、扩展模块等，判断某类下 AI 回答偏好的信息组织方式，指导生产。
• 跟踪购物型 AI 推荐：提取 ai_overview_shopping 中的商品、价格、评分与卖家信息，用于竞品价格监测和电商 SEO 策略优化。
• 比较多地区 AI 搜索表现：结合 location_code、language_code 或 location_coordinate，对比不同国家、城市、语言环境下 AI Mode 的回答差异，支持化 SEO。
• 评估 SERP 可见性位置：开启 calculate_rectangles 获取 AI 模块像素坐标，衡量 AI在页面中的首屏占比和视觉优级。