Yahoo 实时 SERP HTML

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

本接口用于实时获取指定关键词、搜索引擎区域与语言下的搜索结果原始 HTML 页面。

接口说明

• 请求方式：POST
• 接口地址：https://api.seermartech.cn/v3/serp/wp/v2/live/html
• 请求体格式：JSON
• 请求体结构：[{ ... }]

该接口返回搜索结果页的原始 HTML，适合需要自行解析页面结构、提取特殊模块、调试抓取结果的场景。

调用限制

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

计费说明

本接口按请求计费。

参考价约 ¥0.0480 / 次 如设置更高的抓取深度或抓取更多结果页，可能产生额外费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

说明：

• depth过 10 时，如搜索引擎返回 10 条结果，可能增加费用
• 使用 max_crawl_pages 抓取多页时，会按抓取到的 SERP 页数计费
• 使用 stop_crawl_on_match 时，在命中停止条件前抓取的每一页都会计费

请求参数

以下为可用于任务设置的字段。

字段名	类型	说明
url	string	搜索查询直链，可选。可直接传搜索结果 URL，由本接口自动拆解所需参数。此方式处理难度较高，且要求 URL 中准确的语言和地区信息，通常不建议使用。示例：https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8
keyword	string	，填。最大支持 700 个字符。%## 会被解码，字符 + 会被解码为空格。如果中需要保留 %，请写为 %25；如果需要保留 +，请写为 %2B。
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	地理坐标，可选一作为地区定位方式。当未提供 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	搜索引擎域名，可选。系统会根据地区和语言自动选择合适域名，也可手动指定。示例：au.search.yahoo.com、uk.search.yahoo.com、ca.search.yahoo.com
depth	integer	解析深度，可选。表示希望返回的 SERP 结果数量。默认值：10；最大值：200。出 10 可能产生额外费用。
max_crawl_pages	integer	最大抓取页数，可选。表示最多抓取多少个搜索结果页。默认值：1；最大值：100。该参数与 depth合使用。
search_param	string	搜索附加参数，可选。用于传递额外查询参数。
stop_crawl_on_match	array	命中即停止抓取的目标数组，可选。最多支持 10 个目标对象。若设置，响应会返回直到命中指定 match_value 的结果页，并命中项所在页。
match_value	string	停止抓取目标值。当设置 stop_crawl_on_match 时填。可填写域名、子域名或通符模式。注意：域名或子域名不要带请求协议。示例："example.com"、"/blog/post-*"
match_type	string	目标匹类型。当设置 stop_crawl_on_match 时填。可选值：domain（精确域名或子域名）、with_subdomains（主域名及子域名）、wildcard（通符匹）

stop_crawl_on_match 示例

[
 {
 "keyword": "albert einstein",
 "location_code": 2840,
 "language_code": "en",
 "stop_crawl_on_match": [
 {
 "match_type": "domain",
 "match_value": "example.com"
 }
 ]
 }
]

响应结构

接口返回 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	搜索结果项数组

items[] 字段

字段名	类型	说明
page	integer	返回的 HTML 所属结果页序号
date	string	HTML 页面抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +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"
payload = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
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_code": "en",
 "location_code": "2840",
 "keyword": "albert einstein",
 "tag": "tag1",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {}
 ]
 }
 ]
}

错误处理

• 顶层 status_code 表示整个请求的处理状态
• tasks[].status_code 表示单个任务的处理状态
• 建议同时检查：
• HTTP 状态码
• 顶层 status_code
• 任务级 tasks[].status_code

常见错误码与状态说明请参考：/v3/appendix/errors

使用建议

• 优使用 keyword + location_code + language_code 组合，稳定性通常高于直接传 url
• 若只需前 10 条结果，不建议提高 depth，可额外成本
• 如需尽快定位目标站点排名，可结合 stop_crawl_on_match 降低不抓取
• 若要模拟不同终端搜索表现，请显式设置 device 与 os

实用场景

• 抓取原始 SERP 页面，用于自建解析器提取自然结果、新闻模块、问答模块等特殊版块
• 复现指定地区与语言下的搜索页面，帮助排查排名波动、索引异常或 SERP 展现差异
• 对比桌面端与移动端 HTML 结构，识别不同设备下的排名位、广告位和富结果差异
• 监控目标域名是否在指定页码出现，结合 stop_crawl_on_match 提升品牌词或竞品词跟踪效率
• 保存原始 HTML 快，为 SEO 审计、页面结构回溯和搜索结果取证提供底层数据依据