Live Wp V2 SERP 高级实时结果

本接口用于实时获取指定关键词、搜索引擎与地理位置下的前 100 条搜索结果数据。适用于需要即时 SERP 结果的业务场景，并可返回本地结果模块（如 local_pack）等结构化。

接口说明

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

计费说明

本接口按请求计费。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

原文未提供明确单价，因此此处不展示人民币参考价。

调用限制

• 每分钟最多可发起 2000 次 API 调用
• 单次 POST 请求中最多可 100 个任务
• 所有 POST 数据均需使用 JSON 格式（UTF-8 编码）
• 若使用系统标准标识参数（如 keyword、location_code、language_code），任务处理速度通常更快

请求体格式

POST 请求体为 JSON 数组：

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

请求参数

字段名	类型	说明
url	string	搜索查询的完整直达 URL。可选。传后，本接口会自动拆解为所需参数。该方式处理难度较高，且要求 URL 中准确的语言和地域参数，通常不建议优使用。示例：https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
keyword	string	。填（当未通过 url 间接提供时应视为填）。最长支持 700 个字符。所有 %## 会被解码，+ 会被解码为空格。如需在中保留 %，请写为 %25。若 allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site: 等高级搜索运算符，则该任务费用按 5 倍计算。
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	GPS 坐标位置。若未提供 location_name 或 location_code，则填。格式为 latitude,longitude,radius。latitude 与 longitude 最多支持 7 位小数；radius 最小值为 199.9。示例：52.6178549,-155.352142,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
target	string	域名或 URL 匹模式。可选。设置后返回与该目标匹的 SERP素。支持使用通符 * 进行模糊匹。示例：*example.com*（整个域名及子域/页面）；example.com/example-page*（指定前缀 URL）；example.com（首页）；*example.com（任意子域）；example.com/example-page（精确 URL）
se_domain	string	搜索引擎域名。可选。通常系统会根据你提供的位置和语言自动选择适合的域名，也可手动指定。示例：google.co.uk、google.com.au、google.de
depth	integer	解析深度，即返回的 SERP 结果数量。可选。默认值：100；最大值：700。如设置的深度高于返回结果数，差额会自动退回到账户余额。
search_param	string	额外搜索参数。可选。用于附加搜索查询参数。

响应结构

接口返回 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 / object	任务结果集合

任务级字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
post_id	string	你自定义传的任务标识
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix/errors
status_message	string	任务状态说明
time	string	任务执行耗时，单位秒
cost	float	任务费用，单位 USD
result_count	integer	result 数组中的结果数
path	array	URL 路径
data	array / object	请求时提交的数据
result	array	结果数组

结果级字段

字段名	类型	说明
keyword	string	请求中的。返回时 %## 会被解码，+ 会被还原为空格
type	string	请求中的搜索引擎类型
se_domain	string	请求中的搜索引擎域名
location_code	integer	请求中的位置代码
language_code	string	请求中的语言代码
check_url	string	对应搜索结果页直达链接，可用于人工校验结果准确性
datetime	string	结果抓取时间，格式如 2019-11-15 12:57:46 +00:00
target_rankings	array	若设置了 target，此字段返回目标站点在 SERP 中的排名信息
spell	string	搜索引擎自动纠错后的；若无纠错则可能为 null
item_types	array	当前 SERP 中的结果类型列表
se_results_count	integer	SERP 总结果数
items_count	integer	items 中返回的结果数量
items	array	SERP素列表

target_rankings 字段说明

当请求中传 target 时，返回的 target_rankings 会目标站点在 SERP 中的匹结果：

字段名	类型	说明
rank_absolute	integer	目标域名在整个 SERP 中的绝对排名
url	string	与目标匹的 SERP URL

items 中的 local_pack 结果说明

当前文档示例展示的 SERP素类型为 local_pack。

字段名	类型	说明
type	string	素类型，固定为 local_pack
rank_group	integer	在同类型结果组的位置
rank_absolute	integer	在整个 SERP 中的绝对位置
position	string	结果在页面中的布局位置，可见值如 left、right
xpath	string	素的 XPath 路径
title	string	SERP 中显示的标题
description	string	结果描述
domain	string	结果对应域名
phone	string	电话号码
url	string	URL
is_paid	boolean	是否为广告
rating	object / null	评分信息

rating 字段说明

字段名	类型	说明
rating_type	string	评分类型，可见值 Max5、Percents、CustomMax
value	integer	评分值
votes_count	integer	评论/反馈数量
rating_max	integer	当前 rating_type 的评分上限

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/wp/v2/live/advanced" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "post_id": "post ID 1",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/live/advanced"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "post_id": "post ID 1",
 "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 requestSerpLiveAdvanced {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/wp/v2/live/advanced",
 [
 {
 post_id: "post ID 1",
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein",
 },
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 console.log(response.data);
}

requestSerpLiveAdvanced.catch(console.error);

响应示例

{
 "version": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3059 sec.",
 "cost": 0.05,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": {
 "post ID 1": {
 "id": "11151456-0696-0066-0000-002a5915da37",
 "post_id": "post ID 1",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0952 sec.",
 "cost": 0.05,
 "result_count": 1,
 "path": [],
 "data": {
 "se": "wp",
 "se_type": "v2"
 },
 "result": [
 {
 "spell": null,
 "se_results_count": 85,
 "items_count": 1,
 "items": [
 {
 "type": "local_pack",
 "title": "Cipro",
 "snippet": "Subway station nVia Cipro n",
 "domain": null,
 "phone": null,
 "url": null,
 "is_paid": false,
 "rating": null
 }
 ]
 }
 ]
 }
 }
}

状态码与错误处理

可通过以下字段判断请求或任务执行状态：

• 顶层状态：status_code、status_message
• 任务状态：tasks[].status_code、tasks[].status_message

常见处理方式：

• 20000：请求成功
• 状态码：请结合 /v3/appendix/errors 进行排查

建议重点检查以下问题：

• 是否缺少填参数，如 keyword、位置参数、语言参数
• location_name / location_code / location_coordinate 是否重复传或均未传
• language_name / language_code 是否重复传或均未传
• depth 是否出上限
• location_coordinate 格式是否符合 latitude,longitude,radius
• target 是否符合域名或 URL 匹规则

使用建议

• 优使用 location_code + language_code，通常比直接传 url 更稳定、解析更快
• 若只指定站点在结果页中的，可传 target 缩小返回范围
• 若你需要更贴近真实用户设备环境，可根据场景组合 device 与 os
• 大批量调用时，建议为每个任务设置 post_id，便于回溯业务记录
• 若含高级搜索运算符，需提前考虑 5 倍计费影响

实用场景

• 监控本地排名：按城市和语言实时抓取 local_pack 结果，判断门店或客户品牌在本地搜索中的位置。
• 筛选竞品本地露出：通过 target 指定竞品域名，快速识别是否出现在本地搜索结果中，竞对分析。
• 验证多地域搜索差异：切换 location_code 或 location_coordinate，比较同一在不同城市或商圈的 SERP 差异，为区域 SEO 策略提供依据。
• 分析移动端与桌面端差别：组合 device 与 os 获取不同终端下的结果页结构，评估移动优优化是否有效。
• 追踪品牌词纠错与搜索意图变化：利用 spell 字段识别搜索引擎自动纠错，发现用户真实搜索表达与品牌词偏差。