实时获取 SERP HTML（/v3/serp/wp/v2/live/html）

本接口用于按指定关键词、搜索引擎类型和地域实时获取搜索结果页的原始 HTML。适用于需要保存完整页面源码、做自定义解析、校验页面结构或提取平台未结构化输出的场景。

接口说明

• 请求方式：POST
• 接口地址：https://api.seermartech.cn/v3/serp/wp/v2/live/html
• 请求体格式：JSON
• 编码：UTF-8
• 单次 Live 请求支持 1 个任务
• 频率限制：最高 2000 次 API 调用/分钟

计费说明

每次请求都会扣费。

• 基础费用会体现在响应的 cost 字段中
• 当 depth 大于 10 且搜索引擎返回 10 条结果时，可能产生额外费用
• 若以下高级搜索操作符，单任务费用按 5 倍计费： allinanchor:、allintext:、allintitle:、allinurl:、cache:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site:
• load_async_ai_overview=true 时，每次请求会额外收取 参考价约 ¥0.0320 / 次
• 若未返回异步 AI Overview，或该参数未传/为 false，对应额外费用会退回账户余额

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

主参数

字段	类型	填	说明
keyword	string	是	，最长 700 个字符。 %## 会被解码，+ 会被解码为空格。如需传 %，请写为 %25；如需传 +，请写为 %2B。若高级搜索操作符，费用按 5 倍计。
location_code	integer	条件填	搜索地域编码。若已传 location_name 或 location_coordinate，则可不传。示例：2840
language_code	string	条件填	搜索语言编码。若已传 language_name，则可不传。示例：en
depth	integer	否	抓取深度，即期望获取的结果数量。默认 10，最大 200。 10 可能产生额外费用。
device	string	否	设备类型，可选：desktop、mobile。默认 desktop
load_async_ai_overview	boolean	否	是否加载异步 AI Overview。true 表示即使该模块异步加载，也尝试获取；false 返回缓存中已有的 AI Overview。默认 false

附加参数

字段	类型	填	说明
location_name	string	条件填	地域名。若已传 location_code 或 location_coordinate，则可不传。示例：London,England,United Kingdom
language_name	string	条件填	语言名。若已传 language_code，则可不传。示例：English
os	string	否	设备操作系统。device=desktop 时可选 windows、macos，默认 windows；device=mobile 时可选 android、ios，默认 android
tag	string	否	自定义任务标识，最长 255 字符。可用于请求结果匹，响应 data 中会回传该值
stop_crawl_on_match	array	否	命中指定目标后停止抓取。最多可传 10 个目标对象。响应会返回直到命中目标为止的 SERP 结果
max_crawl_pages	integer	否	最大抓取页数，最大 100。每抓取 1 页都会计费（通常每页最多 10 个自然结果）
search_param	string	否	额外搜索参数。不支持的参数：lr、cr、as_qdr、as_sitesearch、as_occt、as_filetype；若传会被自动忽略
expand_ai_overview	boolean	否	是否展开 ai_overview 模块。默认 false
url	string	否	直接传搜索 URL，由本接口自动拆解为对应字段。此方式处理难度较高，且要求 URL 中准确的语言和地域信息，通常不推荐使用
location_coordinate	string	条件填	GPS 坐标，格式为 "latitude,longitude,radius"。纬度/经度最多 7 位小数；radius 范围为 199 到 199999（单位：毫米）。示例：53.476225,-2.243572,200
se_domain	string	否	搜索引擎域名。通常会根据地域和语言自动选择，也可手动指定，如 google.co.uk、google.com.au、google.de
target_search_mode	string	否	目标匹模式，需与 stop_crawl_on_match 一起使用。可选：all、any，默认 any
find_targets_in	array	否	在指定 SERP素类型中查找目标。需与 stop_crawl_on_match 一起使用
ignore_targets_in	array	否	在指定 SERP素类型中忽略目标匹。需与 stop_crawl_on_match 一起使用

stop_crawl_on_match 子字段

字段	类型	填	说明
match_type	string	是	匹类型，可选：domain、with_subdomains、wildcard
match_value	string	是	目标域名、子域名或通表达式。域名不要带协议头。示例："example.com"、"/blog/post-*"

find_targets_in / ignore_targets_in 可选值

• organic
• paid
• local_pack
• featured_snippet
• events
• google_flights
• images
• jobs
• knowledge_graph
• local_service
• map
• scholarly_articles
• third_party_reviews
• twitter

注意：find_targets_in 与 ignore_targets_in 不能相同的类型。

地域与语言查询

可通过以下容路径查询可用地域和语言列表：

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

请求示例

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);

响应结构

接口返回 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 页面抓取时间，格式示例：2019-11-15 12:57:46 +00:00
html	string	搜索结果页原始 HTML

响应示例

{
 "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=0 或 items_count=0

完整错误码与说明请参考容路径：

• /v3/appendix/errors

使用建议

• 若只需标准化结构化结果，优考虑结构化 SERP 接口；本接口更适合需要原始页面源码的场景
• url 方式虽灵活，但稳定性和可控性较弱，推荐优使用显式参数如 keyword、location_code、language_code
• 当你需要判断目标站点是否出现在搜索结果中时，可结合 stop_crawl_on_match、target_search_mode、find_targets_in 使用，以减少无效抓取和成本
• depth 与 max_crawl_pages 会影响抓取范围与费用，建议按分析目标设定

实用场景

• 抓取原始 SERP 页面：获取完整 HTML，用于自建解析器提取暂未结构化输出的模块，提升数据覆盖率
• 校验搜索结果页面结构变化：定期保存 HTML 快，监控搜索引擎页面 DOM 变化，降低解析规则失效风险
• 定位品牌或竞品出现位置：合 stop_crawl_on_match 检查指定域名是否出现在结果页中，快速评估品牌与竞品渗透
• 分析 AI Overview 展示：启用 load_async_ai_overview 和 expand_ai_overview，验证是否触发 AI 概览及页面加载方式
• 还原特定地域设备下的真实结果页：结合 location_code、language_code、device、os 获取更接近真实用户视角的页面源码，用于本地化 SEO 分析