Google News 实时 SERP HTML

POST /v3/serp/google/news/live/html

接口说明

该接口用于实时获取指定关键词、搜索引擎与地区下的 SERP 原始 HTML 页面。默认返回最多 10 条搜索结果对应的 HTML 数据，可用于抓取页面结构、验证结果页展示、调试解析逻辑等场景。

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

该接口为实时请求接口，每次调用都会计费。 参考价约 ¥0.0480 / 次。 如设置更高的抓取深度或命中特殊查询条件，费用可能增加，扣费以响应头 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/wp/locations 获取可用地区及对应代码。示例：2840
language_code	string	条件填	搜索语言代码。当未提供 language_name 时填。提供该字段后，无需再传 language_name。可通过 /v3/serp/wp/languages 获取可用语言及对应代码。示例：en
depth	integer	否	解析深度，即希望返回的结果数量。默认值：10；最大值：200。每 10 条结果为一个计费单位；当 depth > 10 且搜索引擎返回 10 条结果时，可能产生额外费用。如果设定的 depth 大于返回结果数，差额部分会自动退回余额。

附加参数

字段名	类型	填	说明
location_name	string	条件填	搜索地区完整名称。当未提供 location_code 或 location_coordinate 时填。提供后无需再传 location_code 或 location_coordinate。可通过 /v3/serp/wp/locations 获取可用地区名称。示例：London,England,United Kingdom
language_name	string	条件填	搜索语言完整名称。当未提供 language_code 时填。提供后无需再传 language_code。可通过 /v3/serp/wp/languages 获取可用语言名称。示例：English
os	string	否	设备操作系统。该接口提供桌面端结果。可选值：windows、macos。默认：windows
tag	string	否	自定义任务标识，最长 255 个字符。可用于请求与响应结果的业务；响应中的 data 对象会原样返回该值。
max_crawl_pages	integer	否	最多抓取的搜索结果页数，最大值：100。该参数与 depth合使用，用于控制结果抓取范围。
search_param	string	否	额外搜索参数，用于传递搜索引擎支持的附加查询参数。
url	string	否	直接传搜索 URL，本接口会尝试自动拆解为对应字段。该方式处理复杂，且要求 URL 中明确语言和地区信息，一般不建议使用。
location_coordinate	string	条件填	地理坐标定位。当未提供 location_name 或 location_code 时填。格式为：latitude,longitude,radius。纬度和经度最多 7 位小数，radius 最小值 199.9（毫米），最大值 199999（毫米）。示例：53.476225,-2.243572,200
se_domain	string	否	搜索引擎域名。通常系统会根据地区与语言自动选择合适域名，也可手动指定，例如：google.co.uk、google.com.au、google.de

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/google/news/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/google/news/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 main {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/google/news/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	请求路径信息
data	object	请求中提交的参数，会在响应中返回
result	array	结果数组

result 字段说明

字段名	类型	说明
keyword	string	请求中的。返回时 %## 会被解码，+ 会被解码为空格
type	string	请求中的搜索类型
se_domain	string	请求中的搜索引擎域名
location_code	integer	请求中的地区代码
language_code	string	请求中的语言代码
datetime	string	获取结果的时间，UTC 格式，例如：2019-11-15 12:57:46 +00:00
items_count	integer	items 数组中的结果数量
items	array	SERP 中返回的结果项
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": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "7.7543 sec.",
 "cost": 0.003,
 "result_count": 1,
 "path": [
 "v3",
 "serp",
 "google",
 "news",
 "live",
 "html"
 ],
 "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": [
 {
 "keyword": "albert einstein",
 "type": "news",
 "se_domain": "google.com",
 "location_code": 2840,
 "language_code": "en",
 "datetime": "2019-11-15 12:57:46 +00:00",
 "items_count": 1,
 "items": [],
 "page": 1,
 "date": "2019-11-15 12:57:46 +00:00",
 "html": "<html>...</html>"
 }
 ]
 }
 ]
}

---

状态码与错误处理

建议对通用状态码和任务状态码都建立完整的异常处理机制，重点以下几类：

• 请求参数缺失或格式错误
• 不支持的格式（如 cache:）
• 地区、语言或域名组合无效
• 抓取深度或页数出限制
• 接口限流或临时不可用

错误码及状态信息请参考：/v3/appendix/errors

---

使用建议

1. 优使用 location_code + language_code 相比名称字段或直接 URL，更稳定、可控，也更适合程序化调用。

2. 谨提高 depth 过 10 条结果后可能带来额外费用，建议按需求设置。

3. 直接传 url 除非你非常确定 URL 中完整且准确的地区、语言参数，否则容易导致解析偏差。

4. 使用 tag 做业务 便于将接口响应和任务、项目、客户标识进行映射。

实用场景

• 抓取新闻搜索结果页原始 HTML：用于自建解析器、定位页面结构变化，提升新闻 SERP 数据采集稳定性。
• 校验指定的新闻结果展示：核对某个品牌、人物或事件在新闻搜索中的页面呈现，舆监测与审核。
• 对比不同地区或语言下的新闻页面差异：分析同一主题在不同国家/语言环境中的结果排序与页面结构，支持 SEO 与传播研究。
• 回放与排查解析异常：当结构化字段提取失败时，直接查看原始 HTML，快速定位选择器失效或页面改版问题。
• 构建新闻 SERP 存档样本：保存时间点的新闻结果页 HTML，为竞品分析、热点追踪和搜索表现复盘提供证据。