SERP / WordPress V2 实时 HTML

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

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

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

该接口返回未经解析的 SERP HTML，适合需要自行提取页面、调试搜索结果结构或保留原始页面快的场景。

计费说明

本接口按请求计费。

参考价约 ¥0.0480 / 次 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

注意：

• 每分钟最多可发送 2000 次 API 调用；
• 每次 Live SERP 请求只能 1 个任务；
• 所有 POST 数据使用 UTF-8 编码的 JSON；
• 请求体是 JSON 数组格式：[{ ... }]

如果设置了更高的 depth：

• 桌面端 20 条结果；
• 移动端 10 条结果；

且搜索引擎返回了更多结果，可能产生额外费用。 若设置的 depth 高于最终响应中的结果数，差额会自动退回余额。

请求参数

主要参数

字段名	类型	填	说明
keyword	string	是	，最长支持 700 个字符。请求中的 %## 会被解码，+ 会被解码为空格。如需保留 %，请写为 %25；如需保留 +，请写为 %2B。
location_code	integer	条件填	搜索地区编码。当未提供 location_name 或 location_coordinate 时填。若使用该字段，则无需再传 location_name 或 location_coordinate。示例：2840。地区列表可通过 /v3/serp/wp/locations 获取。
language_code	string	条件填	搜索语言编码。当未提供 language_name 时填。若使用该字段，则无需再传 language_name。示例：en。语言列表可通过 /v3/serp/wp/languages 获取。
depth	integer	否	抓取深度，即 SERP 中返回的结果数量。桌面端默认 20，最大 100；移动端默认 10，最大 100。
device	string	否	设备类型，可选：desktop、mobile。默认：desktop。

附加参数

字段名	类型	填	说明
location_name	string	条件填	搜索地区完整名称。当未提供 location_code 或 location_coordinate 时填。若使用该字段，则无需再传 location_code 或 location_coordinate。示例：London,England,United Kingdom。地区列表可通过 /v3/serp/wp/locations 获取。
language_name	string	条件填	搜索语言完整名称。当未提供 language_code 时填。若使用该字段，则无需再传 language_code。示例：English。语言列表可通过 /v3/serp/wp/languages 获取。
os	string	否	设备操作系统。若 device=desktop，可选 windows、macos，默认 windows；若 device=mobile，可选 android、ios，默认 android。
tag	string	否	自定义任务标识，最长 255 字符。可用于请求结果映射，响应中的 data 对象会返回该值。
location_coordinate	string	条件填	GPS 坐标。当未提供 location_name 或 location_code 时填。格式：latitude,longitude,zoom。如未传 zoom，默认使用 9z。经纬度最多支持 7 位小数；zoom 最小 4z，最大 18z。示例：52.6178549,-155.352142,20z。
min_rating	string	否	按最低评分筛选结果。桌面端可选：3.5、4、4.5；移动端可选：2、2.5、3、3.5、4、4.5。
time_filter	string	否	按营业时间筛选地点。注意：搜索引擎仍可能返回不符合该筛选条件的结果。可选值："open_now"、"24_hours"、"$day_value"、"$day_value;$time_value"。$day_value 可为 monday 至 sunday；$time_value 可为 00 至 23。示例："tuesday;18"。

请求示例

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 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	通用状态信息。
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:minutes:UTC_difference_hours:UTC_difference_minutes。示例：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_name": "English",
 "location_name": "United States",
 "keyword": "local nail services",
 "tag": "tag1",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code=20000 通常表示请求成功；
• 单个任务也有独立的 status_code 与 status_message；
• 建议同时检查：
• 顶层 status_code
• tasks_error
• tasks[].status_code

完整错误码说明参考 /v3/appendix/errors。

使用说明

• 本接口为实时接口，提交后直接返回结果；
• 每次请求只能提交一个任务对象，但请求体仍需使用数组格式：

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

• 如需按地区或语言名称传参，可使用 location_name、language_name 替代编码字段；
• 如需更精确地控制本地化搜索范围，可使用 location_coordinate 传经纬度与缩放级别；
• 返回的是原始 HTML，不是结构化搜索结果，适合自定义解析流程。

实用场景

• 抓取原始 SERP 页面：获取指定在目标地区的完整搜索结果 HTML，用于自定义解析搜索模块、广告位、本地结果块等页面。
• 校验搜索结果展示差异：对比不同设备、系统、地区下的 HTML 差异，帮助 SEO 团队识别本地化展示、移动端样式和排序变化。
• 构建自有解析器：基于 html 字段自行提取标题、链接、摘要或特殊 SERP 组件，满足标准结构化接口之外的个性化数据需求。
• 留存页面快：保存特定时点的 SERP HTML，便于后续复盘排名波动、页面结构调整或搜索引擎样式更新。
• 验证时间与评分筛选效果：结合 time_filter、min_rating 等参数测试本地结果筛选逻辑，门店 SEO、地图可见性分析与竞品监测。