SERP / Google Images 实时获取 HTML

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

本接口用于实时获取指定关键词、搜索引擎与地理位置下的原始 SERP HTML 页面。接口会返回搜索结果页面的 HTML 源码，可用于自定义解析、结果存档、页面结构监控等场景。

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

说明：原文标题与示例路径存在不一致之处。本文保留平台 API 容路径 /v3/serp/wp/v2/live/html 及技术细节。

计费说明

每次请求都会产生费用。

• 参考价约 ¥0.0480 / 次
• 若返回结果 100 条，可能因抓取更多 SERP 页面而产生额外费用
• 若设置的 depth 高于返回结果数，差额费用通常会自动退回余额
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求说明

所有 POST 数据均需使用 JSON（UTF-8 编码）提交。

• 请求体为 JSON 数组格式：[{ ... }]
• 单次 Live SERP 请求支持 1 个任务
• 接口速率上限：每分钟最多 2000 次 API 调用

---

主要参数

字段名	类型	说明
keyword	string	填。搜索，最长支持 700 个字符。 %## 会被解码，+ 会被解码为空格。如需传 %，请写为 %25；如需传 +，请写为 %2B。若 allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site: 等高级搜索运算符，则该任务费用按 5 倍计费。 cache: 的查询不受支持，会返回校验错误。
location_code	integer	当未指定 location_name 或 location_coordinate 时填。搜索引擎地域代码。若已使用该字段，则无需再传 location_name 或 location_coordinate。可通过 /v3/serp/google/locations 获取可用地域列表。示例：2840
language_code	string	当未指定 language_name 时填。搜索引擎语言代码。若已使用该字段，则无需再传 language_name。可通过 /v3/serp/google/languages 获取可用语言列表。示例：en
depth	integer	可选。解析深度，即期望获取的 SERP 结果数量。默认值：100；最大值：700。每最多 100 条结果的 SERP 会单独计费；若设置 100，且搜索引擎返回更多结果，可能产生额外费用。

---

附加参数

字段名	类型	说明
location_name	string	当未指定 location_code 或 location_coordinate 时填。完整地域名称。若使用该字段，则无需再传 location_code 或 location_coordinate。可通过 /v3/serp/google/locations 获取可用地域名称。示例：London,England,United Kingdom
language_name	string	当未指定 language_code 时填。完整语言名称。若使用该字段，则无需再传 language_code。可通过 /v3/serp/google/languages 获取可用语言名称。示例：English
os	string	可选。设备操作系统。注意：该接口提供桌面端结果。可选值：windows、macos。默认值：windows
tag	string	可选。自定义任务标识，最长 255 个字符。可用于将请求与返回结果进行业务；响应中的 data 对象会原样返回该值。
max_crawl_pages	integer	可选。最大抓取页数，表示最多抓取多少个搜索结果页。最大值：100。该参数与 depth合使用。
search_param	string	可选。搜索查询附加参数，用于补搜索行为控制。
url	string	可选。直接传搜索 URL，本平台会自动拆解为对应字段。该方式处理难度更高，且要求 URL 中已精确指定语言与地区，通常不建议优使用。示例：https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en...
location_coordinate	string	当未指定 location_name 或 location_code 时填。地理坐标，格式为 "latitude,longitude,radius"。latitude 与 longitude 最多支持 7 位小数；radius 最小值为 199.9（毫米），最大值为 199999（毫米）。示例：53.476225,-2.243572,200
se_domain	string	可选。搜索引擎域名。系统会根据语言和地区自动选择合适域名，也可手动指定。示例：google.co.uk、google.com.au、google.de

---

返回结果说明

接口返回 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 数组中返回错误的任务数量
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	请求路径
data	object	与提交时请求参数对应的数据对象
result	array	结果数组

result 数组字段

字段名	类型	说明
keyword	string	POST 中提交的。返回时 %## 会被解码，+ 会被解码为空格
type	string	POST 中指定的搜索引擎类型
se_domain	string	POST 中的搜索引擎域名
location_code	integer	POST 中的地域代码
language_code	string	POST 中的语言代码
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

---

请求示例

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 fetchSerpHtml {
 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);
}

fetchSerpHtml.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_name": "English",
 "location_name": "United States",
 "keyword": "albert einstein",
 "tag": "tag1",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {}
 ]
 }
 ]
}

---

状态码与错误处理

• 顶层 status_code 表示整次请求处理状态
• tasks[].status_code 表示单个任务处理状态
• 建议同时处理 HTTP 层错误、接口层错误以及任务级错误
• 完整错误码列表参考：/v3/appendix/errors

建议在生产环境中建立统一的异常处理与重试机制，参数校验错误、额限制、地域/语言不匹等。

使用建议

1. 优使用 keyword + location_code + language_code 的标准方式发起请求，稳定性更高。
2. url 参数适用于已掌握完整搜索 URL 结构的场景。
3. 若只需前 100 条结果，建议保持默认 depth=100，以便控制成本。
4. 如需抓取更多分页，可结合 depth 与 max_crawl_pages 精细控制抓取范围。
5. 返回的是原始 HTML，后续需由业务侧自行解析 DOM、抽取模块或存档。

实用场景

• 抓取图片搜索结果页源码：获取图片搜索 SERP 原始 HTML，用于解析缩略图、来源站点、图片模块结构等数据。
• 监控页面结构变化：定期拉取同一的 HTML，对比搜索结果页面 DOM 变化，及时发现搜索引擎版式调整。
• 验证地域化展示差异：按不同国家、语言或坐标请求 HTML，分析同一在不同市场下的图片结果布局差异。
• 构建自定义解析器：基于原始 HTML 自行提取图片卡片、搜索、分页等，满足标准字段之外的深度分析需求。
• 留存 SERP 取证快：保存特定时间点的页面源码，用于 SEO 复盘、竞品观察或异常波动排查。