Google Local Pack 实时 SERP HTML

本接口用于实时获取指定关键词、搜索引擎、语言与地区下的搜索结果原始 HTML 页面。适合需要自行解析页面结构、提取特殊模块或做页面级存档的场景。

接口说明

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

说明：该接口为实时接口，每次请求都会计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有 POST 数据使用 JSON（UTF-8 编码）提交。 任务参数需要放在通用 POST 数组中，即请求体格式为：

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

调用限制

• 每分钟最多可发送 2000 次 API 调用
• 每次 Live SERP 请求 只能 1 个任务

---

请求参数

任务提交字段

字段名	类型	说明
url	string	搜索查询的直接 URL。可选。可直接传完整搜索 URL，系统会自动拆解为所需参数。该方式处理复杂，且要求 URL 中已准确语言和地区信息，通常不推荐。示例：https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
keyword	string	填。，最长 700 个字符。 %## 会被解码，+ 会被解码为空格。如需保留 %，请写为 %25；如需保留 +，请写为 %2B。若 allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site: 等高级搜索操作符，则单任务费用按 5 倍计费。**注意：**含 cache: 的查询不受支持，会返回校验错误。
location_name	string	搜索地区完整名称。若未传 location_code 或 location_coordinate，则此字段填。传后无需再传 location_code 或 location_coordinate。可通过 /v3/serp/wp/locations 获取可用地区。示例：London,England,United Kingdom
location_code	integer	搜索地区编码。若未传 location_name 或 location_coordinate，则此字段填。传后无需再传 location_name 或 location_coordinate。可通过 /v3/serp/wp/locations 获取可用地区编码。示例：2840
location_coordinate	string	GPS 坐标定位。若未传 location_name 或 location_code，则此字段填。格式：latitude,longitude,radius。纬度和经度最多 7 位小数；radius 最小值 199.9 毫米，最大值 199999 毫米。示例：53.476225,-2.243572,200
language_name	string	搜索语言完整名称。若未传 language_code，则此字段填。传后无需再传 language_code。可通过 /v3/serp/wp/languages 获取可用语言。示例：English
language_code	string	搜索语言编码。若未传 language_name，则此字段填。传后无需再传 language_name。可通过 /v3/serp/wp/languages 获取可用语言编码。示例：en
device	string	设备类型。可选。可选值：desktop、mobile。默认：desktop
os	string	设备操作系统。可选。若 device=desktop，可选 windows、macos，默认 windows；若 device=mobile，可选 android、ios，默认 android
se_domain	string	搜索引擎域名。可选。系统通常会根据地区和语言自动选择合适域名，也可手动指定，如：google.co.uk、google.com.au、google.de
depth	integer	解析深度，即需要的 SERP 结果数量。可选。默认：10；最大值：200。每最多 10 条结果的 SERP 会计费一次；若 depth 大于 10，且搜索引擎返回 10 条结果，可能产生额外费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
max_crawl_pages	integer	最大抓取页数。可选。最大值：100。系统会按抓取到的每一页计费（通常每页 10 条自然结果）。该参数与 depth合使用。
search_param	string	搜索附加参数。可选。用于传递额外的搜索请求参数。
load_async_ai_overview	boolean	是否加载异步 AI Overview。可选。设为 true 时，即使该模块为异步加载，也会尝试获取 ai_overview 项；设为 false 时返回缓存中的 ai_overview。默认：false。启用后每次请求会额外收费 USD 0.002，参考价约 ¥0.0320 / 次。若响应中该缺失或值为 false，附加费用会退回到账户余额。
expand_ai_overview	boolean	是否展开 AI Overview。可选。设为 true 时展开 ai_overview 项。默认：false
tag	string	自定义任务标识。可选。最长 255 个字符。可用于请求与结果的业务，返回结果会在 data 对象中原样带回该值。

---

响应结构

接口返回 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 中找到的结果项

items 数组字段

字段名	类型	说明
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, json=data, headers=headers)
print(response.json)

TypeScript

import axios from "axios";

async function main {
 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);
}

main.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": [
 {}
 ]
 }
 ]
}

---

错误处理

建议对以下层级分别做异常处理：

1. HTTP 请求失败：如网络错误、时、4xx/5xx
2. 顶层状态异常：检查 status_code 与 status_message
3. 任务级异常：逐个检查 tasks[].status_code
4. 结果为空：检查 result_count、items_count 是否为 0

常见错误码、状态信息请参考：

• /v3/appendix/errors

---

使用建议

• 如果只是按、地区、语言标准抓取，优使用 keyword + location + language 方式，不建议直接传 url
• 若需要更贴近真实用户环境，可合 device、os、se_domain 精细控制抓取条件
• 若抓取深度较大，请同时评估 depth 与 max_crawl_pages 对费用和性能的影响
• 若只需结构化 SERP 数据，优考虑结构化结果接口；本接口更适合需要原始 HTML 的场景

实用场景

• 抓取 本地搜索结果页原始 HTML，用于自研解析器提取 Local Pack 卡片、商家信息与页面模块，提升本地 SEO 监测灵活性
• 对比 不同地区、语言、设备下的 SERP HTML 差异，定位本地化排名展示变化，多城市门店优化
• 存档 查询词的实时页面快，保留搜索结果原始证据，便于复盘排名波动或客户汇报
• 校验 页面中 AI Overview、特殊模块或异步加载是否真实出现，帮助判断新 SERP 形态对自然流量的影响
• 训练 自定义 SERP 解析规则与特征识别模型，基于原始 HTML 提升对本地、知识面板、地图模块等结果的识别能力