主题
实时高级自然搜索结果接口
POST /v3/serp///live/advanced
接口概述
实时 SERP(搜索结果页)高级接口用于按指定关键词、搜索引擎、地区和语言,实时抓取自然搜索结果,并返回结构化的完整 SERP 数据。 除普通自然结果外,本接口还会返回精选摘要、知识图谱、People Also Ask、图片、视频、本地、AI Overview 等扩展,并可选返回像素坐标信息。
- 请求方式:
POST - 容路径:
/v3/serp///live/advanced - 基础域名:
https://api.seermartech.cn
说明:
- 所有 POST 数据使用 UTF-8 编码的 JSON;
- 请求体为 JSON 数组
[{ ... }];- 单次 Live SERP 请求支持 1 个任务;
- 速率上限为每分钟最多 2000 次 API 调用;
- 实扣费以响应头
X-SeerMarTech-Charge-CNY为准。
计费说明
本接口按请求计费。若使用部分增强参数,会产生额外费用:
load_async_ai_overview=true:参考价约¥0.0320 / 次calculate_rectangles=true:参考价约¥0.0320 / 次people_also_ask_click_depth:每次展开点击参考价约¥0.0024 / 次
规则:
depth默认抓取 10 条结果; 10 条时,如搜索引擎返回更多结果,可能产生额外费用;stop_crawl_on_match/max_crawl_pages启用后,按爬取到的 SERP 页数或目标范围计费;- 若启用了异步 AI Overview 或 PAA 点击扩展,但页面未出现相应或点击次数少于设置值,多收部分会返还到账户余额;
- 若
keyword含某些高级搜索运算符,任务费用会乘以 5。
请求参数
主要参数
| 字段 | 类型 | 填 | 说明 |
|---|---|---|---|
keyword | string | 是 | 查询,最长 700 个字符。字段中的 %## 会被解码,+ 会被解码为空格;如需保留 %,请写为 %25;如需保留 +,请写为 %2B。若 allinanchor:、allintext:、allintitle:、allinurl:、cache:、define:、definition:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、site: 等搜索运算符,费用将按 5 倍计。 |
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 结果数量。默认 10,最大 200。 10 条时可能产生额外费用。 |
device | string | 否 | 设备类型,可选:desktop、mobile。默认 desktop。 |
load_async_ai_overview | boolean | 否 | 是否加载异步 AI Overview。设为 true 时,即使该为异步加载,也会尝试获取;设为 false 时返回缓存中可获得的 ai_overview。默认 false。启用会产生额外费用。若响应中该不存在或 asynchronous_ai_overview=false,额外费用会返还。 |
附加参数
| 字段 | 类型 | 填 | 说明 |
|---|---|---|---|
location_name | string | 条件填 | 搜索地区名。当未提供 location_code 或 location_coordinate 时填。示例:London,England,United Kingdom |
language_name | string | 否 | 搜索语言名。示例:English |
os | string | 否 | 设备操作系统。device=desktop 时可选 windows、macos,默认 windows;device=mobile 时可选 android、ios,默认 android。 |
tag | string | 否 | 用户自定义任务标识,最长 255 字符。会原样出现在响应的 data 对象中。 |
stop_crawl_on_match | array | 否 | 命中目标即停止爬取。最多支持 10 个目标对象,每个对象 match_type 和 match_value。响应将返回直到匹目标为止的结果。按爬取范围计费。 |
match_type | string | 条件填 | 当设置 stop_crawl_on_match 时填。可选:domain(指定域名/子域名)、with_subdomains(主域名及子域名)、wildcard(通符模式)。 |
match_value | string | 条件填 | 当设置 stop_crawl_on_match 时填。填写目标域名、子域名或通值,不要带协议头。示例:"match_value": "example.com"、"match_value": "/blog/post-*" |
max_crawl_pages | integer | 否 | 最多爬取多少页搜索结果,最大 100。每页按 10 个自然结果计费。与 depth 决定抓取范围。 |
search_param | string | 否 | 额外搜索参数。部分参数不支持,若传将被自动忽略:lr、cr、as_qdr、as_sitesearch、as_occt、as_filetype。 |
remove_from_url | array | 否 | 从结果 URL 中移除特定参数,最多 10 个。若同时设置 target,会移除这些参数再执行匹。 |
people_also_ask_click_depth | integer | 否 | 展开 people_also_ask 的点击层级,用于获取更多 people_also_ask_element。取值范围 1-4。每次点击有额外费用,未发生的点击费用会返还。 |
group_organic_results | boolean | 否 | 是否将同域结果作为主自然结果的 related_result 返回。默认 true。设为 false 时,related_result 会作为独立 organic 结果返回。 |
calculate_rectangles | boolean | 否 | 是否计算 SERP素的像素位置和尺寸。默认 false。启用后会返回 rectangle 对象,并产生额外费用。 |
browser_screen_width | integer | 否 | 浏览器屏幕宽度,范围 240-9999。在 calculate_rectangles=true 时生效。默认:桌面 1920,Android 手机 360,iOS 手机 375。 |
browser_screen_height | integer | 否 | 浏览器屏幕高度,范围 240-9999。在 calculate_rectangles=true 时生效。默认:桌面 1080,Android 手机 640,iOS 手机 812。 |
browser_screen_resolution_ratio | integer | 否 | 屏幕分辨率比,范围 0.5-3。在 calculate_rectangles=true 时生效。默认:桌面 1,Android/iOS 手机 3。 |
url | string | 否 | 直接传搜索 URL,由本接口自动解析为查询参数。该方式处理难度最高,且要求 URL 中已准确语言和地区信息,通常不建议使用。URL 中若不支持的搜索参数,也会被自动忽略。 |
location_coordinate | string | 否 | GPS 定位参数,格式为 "latitude,longitude,radius"。纬度和经度最多 7 位小数;radius 范围 199-199999(毫米)。示例:53.476225,-2.243572,200 |
se_domain | string | 否 | 搜索引擎域名。通常系统会根据地区和语言自动选择,也可手动指定,例如 google.co.uk、google.com.au、google.de。 |
target | string | 否 | 只返回特定目标域名、子域名或网页 URL 的 SERP素。域名/子域名不要带 https:// 和 www.。支持通符 *。 |
target_search_mode | string | 否 | 多目标匹停止模式。需与 stop_crawl_on_match 一起使用。可选:all、any,默认 any。all 表示所有目标都命中才停止;any 表示命中任一目标即停止。 |
find_targets_in | array | 否 | 指定在哪些 SERP素类型中检查目标匹。需与 stop_crawl_on_match 一起使用。若不传,则默认检查所有 url 和 domain 的一级。不可与 ignore_targets_in含相同类型。 |
ignore_targets_in | array | 否 | 指定在哪些 SERP素类型中忽略目标匹。需与 stop_crawl_on_match 一起使用。不可与 find_targets_in含相同类型。 |
target 支持的匹示例
| 写法 | 含义 |
|---|---|
example.com | 匹站点首页,例如 https://example.com 或 https://www.example.com/ |
example.com* | 匹该域名下所有页面 |
*example.com* | 匹整个主域名及子域名和页面 |
*example.com | 匹任意子域名下的首页 |
example.com/example-page | 精确匹该 URL |
example.com/example-page* | 匹以该路径前缀开头的 URL |
find_targets_in / ignore_targets_in 可选值
organicpaidlocal_packfeatured_snippeteventsgoogle_flightsimagesjobsknowledge_graphlocal_servicemapscholarly_articlesthird_party_reviewstwitter
请求示例
cURL
bash
curl --location --request POST "https://api.seermartech.cn/v3/serp/{{low_se_name}}/{{low_se_type}}/live/advanced" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein",
"calculate_rectangles": true
}
]'Python
python
import requests
url = "https://api.seermartech.cn/v3/serp/{{low_se_name}}/{{low_se_type}}/live/advanced"
headers = {
"Authorization": "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json"
}
data = [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein",
"calculate_rectangles": True
}
]
response = requests.post(url, headers=headers, json=data)
print(response.json)TypeScript
typescript
import axios from "axios";
async function run {
const response = await axios.post(
"https://api.seermartech.cn/v3/serp/{{low_se_name}}/{{low_se_type}}/live/advanced",
[
{
language_code: "en",
location_code: 2840,
keyword: "albert einstein",
calculate_rectangles: true
}
],
{
headers: {
Authorization: "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json"
}
}
);
console.log(response.data);
}
run.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 | 任务结果数组 |
任务级字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID,UUID 格式 |
status_code | integer | 任务状态码 |
status_message | string | 任务状态信息 |
time | string | 任务执行耗时 |
cost | float | 单任务成本,单位 USD |
result_count | integer | result 数组数 |
path | array | URL 路径 |
data | object | 原始请求参数回显 |
result | array | 结果数组 |
结果级通用字段
| 字段 | 类型 | 说明 |
|---|---|---|
keyword | string | 请求,返回时 %## 会被解码,+ 会被转为空格 |
type | string | 搜索类型 |
se_domain | string | 搜索引擎域名 |
location_code | integer | 地区编码 |
language_code | string | 语言编码 |
check_url | string | 搜索结果直链,可用于人工校验 |
datetime | string | 结果抓取时间,UTC 格式:yyyy-mm-dd hh-mm-ss +00:00 |
spell | object | 搜索引擎自动纠错信息 |
refinement_chips | object | 搜索建议筛选项 |
item_types | array | 本次 SERP 中出现的类型集合 |
se_results_count | integer | SERP 结果总量 |
pages_count | integer | 实抓取的 SERP 页数 |
items_count | integer | items 数组中的数量 |
items | array | SERP素数组 |
spell 字段
| 字段 | 类型 | 说明 |
|---|---|---|
keyword | string | 搜索引擎纠错后的 |
type | string | 纠错类型:did_you_mean、showing_results_for、no_results_found_for、including_results_for |
refinement_chips 字段
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 refinement_chips |
xpath | string | 素 XPath |
items | array | 筛选项列表 |
refinement_chips.items[]:
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 refinement_chips_element |
title | string | 筛选项标题 |
url | string | 筛选后的搜索 URL |
domain | string | SERP 中域名 |
options | array | 进一步筛选选项 |
主要 SERP素说明
由于高级 SERP 返回的类型非常多,下面保留最核心、最常用且最业务价值的字段结构。响应中还可能出现更多类型,字段命名与结构保持容。
1) organic 自然结果
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 organic |
rank_group | integer | 同类型中的组排名 |
rank_absolute | integer | 整个 SERP 中的绝对排名 |
page | integer | 所在搜索结果页码 |
position | string | 版位位置:left / right |
xpath | string | 素 XPath |
domain | string | 域名 |
title | string | 标题 |
url | string | 目标 URL |
cache_url | string | 缓存页 URL |
related_search_url | string | 站点搜索 URL |
breadcrumb | string | 面屑 |
website_name | string | 网站名称 |
is_image | boolean | 是否带图 |
is_video | boolean | 是否带视频 |
is_featured_snippet | boolean | 是否为精选摘要来源 |
is_malicious | boolean | 是否被标记为恶意站点 |
is_web_story | boolean | 是否为 Web Story |
description | string | 摘要描述 |
pre_snippet | string | 描述前附加信息 |
extended_snippet | string | 描述后附加信息 |
images | array | 图片列表 |
amp_version | boolean | 是否有 AMP 版本 |
rating | object | 评分信息 |
price | object | 价格信息 |
highlighted | array | 描述中加粗词 |
links | array | 站点链接(sitelinks) |
faq | object | FAQ 扩展,已废弃,固定返回 null |
extended_people_also_search | array | 返回搜索结果页后出现的搜索扩展 |
about_this_result | object | “此结果”面板信息 |
related_result | array | 同域结果 |
timestamp | string | 结果发布时间 |
rectangle | object | 像素坐标信息;在 calculate_rectangles=true 时返回 |
rating
| 字段 | 类型 | 说明 |
|---|---|---|
rating_type | string | 评分类型:Max5、Percents、CustomMax |
value | float | 评分值 |
votes_count | integer | 评论/评分数量 |
rating_max | integer | 评分上限 |
price
| 字段 | 类型 | 说明 |
|---|---|---|
current | float | 当前价格 |
regular | float | 原价 |
max_value | float | 最高价格 |
currency | string | 货币 ISO 代码 |
is_price_range | boolean | 是否为区间价格 |
displayed_price | string | 搜索结果中原始价格文本 |
about_this_result
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 about_this_result_element |
url | string | 结果 URL |
source | string | 信息来源 |
source_info | string | 来源描述 |
source_url | string | 来源页 URL |
language | string | 结果语言 |
location | string | 结果适用地区 |
search_terms | array | 命中的搜索词 |
related_terms | array | 词 |
rectangle
| 字段 | 类型 | 说明 |
|---|---|---|
x | integer | 左上角横坐标 |
y | integer | 左上角纵坐标 |
width | integer | 素宽度(像素) |
height | integer | 素高度(像素) |
2) paid 付费结果
核心字段与 organic 类似,常用补字段:
| 字段 | 类型 | 说明 |
|---|---|---|
website_name | string | 广告主网站名称 |
extra.ad_aclk | string | 广告标识符 |
description_rows | array | 扩展描述行 |
links | array | 广告附加链接 |
price | object | 价格信息 |
rating | object | 评分信息 |
rectangle | object | 像素坐标信息 |
3) featured_snippet 精选摘要
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 featured_snippet |
domain | string | 来源域名 |
title | string | 结果标题 |
featured_title | string | 精选摘要来源页标题 |
description | string | 摘要 |
timestamp | string | 发布时间 |
url | string | 来源 URL |
images | array | 图片 |
table | object | 表格型摘要数据 |
rectangle | object | 像素坐标信息 |
4) people_also_ask 大家还会问
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 people_also_ask |
items | array | 问题列表 |
rectangle | object | 像素坐标信息 |
people_also_ask.items[]:
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 people_also_ask_element |
title | string | 问题标题 |
seed_question | string | 触发扩展问题的原始问题 |
xpath | string | 素 XPath |
expanded_element | array | 展开后的答案 |
当设置
people_also_ask_click_depth时,可获得更多扩展问题及答案。
5) knowledge_graph 知识图谱
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 knowledge_graph |
title | string | 实体名称 |
subtitle | string | 副标题/实体类别 |
description | string | 实体简介 |
card_id | string | 卡片 ID |
url | string | 官方或主要链接 |
image_url | string | 主图 |
logo_url | string | Logo |
cid | string | 实体 CID |
items | array | 图谱子 |
rectangle | object | 像素坐标信息 |
知识图谱可能多种子项:
knowledge_graph_images_itemknowledge_graph_list_itemknowledge_graph_ai_overview_itemknowledge_graph_description_itemknowledge_graph_row_itemknowledge_graph_carousel_itemknowledge_graph_part_itemknowledge_graph_expanded_itemknowledge_graph_shopping_itemknowledge_graph_hotels_booking_item
这些子项通常标题、链接、图片、文本、表格、引用、价格、日期、矩形坐标等结构化数据。
6) ai_overview AI 概览
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 ai_overview |
rank_group | integer | 组排名 |
rank_absolute | integer | 绝对排名 |
page | integer | 页码 |
position | string | 位置:left / right |
xpath | string | 素 XPath |
asynchronous_ai_overview | boolean | 是否为异步加载 |
markdown | string | AI Overview 的 Markdown |
items | array | 概览子项 |
references | array | 引用来源 |
rectangle | object | 像素坐标信息 |
ai_overview.items[] 常见类型:
ai_overview_element:文本主体ai_overview_video_element:视频片段ai_overview_table_element:表格ai_overview_expanded_element:可展开扩展
ai_overview_reference 常见字段:
| 字段 | 类型 | 说明 |
|---|---|---|
source | string | 引用来源名称 |
domain | string | 引用域名 |
url | string | 引用页面 URL |
title | string | 引用页面标题 |
text | string | 被引用的文本片段 |
7) 常见 SERP素类型
响应中的 items 还可能以下类型:
answer_boxcarouselmulti_carouselrelated_searchespeople_also_searchlocal_packhotels_packtop_storiestwittermapgoogle_flightsgoogle_reviewsthird_party_reviewsgoogle_postsvideoappimagesshoppingjobseventsmention_carouselrecipestop_sightsscholarly_articlespopular_productspodcastsquestions_and_answersfind_results_onstocks_boxvisual_storiescommercial_unitslocal_servicesgoogle_hotelsmath_solvercurrency_boxcoursesproduct_considerationsshort_videosfound_on_webrefine_productsexplore_brandsperspectivesdiscussions_and_forumscompare_sites
这些通常以下通用字段:
typerank_grouprank_absolutepagepositionxpathtitleurldomainitemsratingpricetimestamprectangle
响应示例
以下为根据示例整理后的精简版响应保留结构,便于理解。
json
{
"version": "0.1.20200129",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.3059 sec.",
"cost": 0.003,
"tasks_count": 1,
"tasks_error": 0,
"tasks": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.3059 sec.",
"cost": 0.003,
"result_count": 1,
"path": [
"v3",
"serp",
"google",
"organic",
"live",
"advanced"
],
"data": {
"api": "serp",
"function": "live",
"se": "google",
"se_type": "organic",
"language_name": "English",
"location_name": "United States",
"keyword": "flight ticket new york san francisco",
"tag": "tag2",
"device": "desktop",
"os": "windows"
},
"result": [
{
"keyword": "flight ticket new york san francisco",
"type": "organic",
"se_domain": "google.com",
"location_code": 2840,
"language_code": "en",
"datetime": "2024-01-01 12:00:00 +00:00",
"item_types": [
"organic",
"paid",
"featured_snippet",
"people_also_ask",
"knowledge_graph",
"ai_overview"
],
"se_results_count": 85600000,
"pages_count": 1,
"items_count": 6,
"items": [
{
"type": "organic",
"rank_group": 26,
"rank_absolute": 30,
"page": 1,
"position": "left",
"domain": "www.t-mobile.com",
"title": "Apple iPhone 12 Pro 5G | 4 colors in 512GB, 256GB & 128GB",
"url": "https://www.t-mobile.com/cell-phone/apple-iphone-12-pro",
"breadcrumb": "https://www.t-mobile.com › Phones › Apple",
"website_name": "T-Mobile",
"description": "Get a great deal on the 5G-ready Apple iPhone 12 Pro.",
"rating": {
"rating_type": "Max5",
"value": 4,
"votes_count": 231,
"rating_max": 5
},
"price": {
"current": 30,
"regular": null,
"max_value": 899.99,
"currency": "USD",
"is_price_range": true,
"displayed_price": "US$30.00 to US$899.99"
},
"rectangle": {
"x": 180,
"y": 5814,
"width": 652,
"height": 363
}
},
{
"type": "featured_snippet",
"rank_group": 1,
"rank_absolute": 10,
"page": 1,
"position": "left",
"domain": "www.rome.net",
"title": "Rome Metro - Lines, hours, fares and Rome metro maps",
"description": "Most important metro stations...",
"timestamp": "2020-09-11 14:42:55 +00:00",
"url": "https://www.rome.net/metro"
},
{
"type": "people_also_ask",
"rank_group": 1,
"rank_absolute": 3,
"page": 1,
"position": "left",
"items": [
{
"type": "people_also_ask_element",
"title": "What is the difference between HIDS and NIDS?"
}
]
},
{
"type": "knowledge_graph",
"rank_group": 1,
"rank_absolute": 1,
"page": 1,
"position": "right",
"title": "Eminem",
"subtitle": "American rapper",
"description": "Marshall Bruce Mathers III, known professionally as Eminem..."
},
{
"type": "paid",
"rank_group": 1,
"rank_absolute": 1,
"page": 1,
"position": "left",
"title": "Cheap Flights to Boston - Roundtrip starting from $97",
"domain": "www.expedia.com",
"website_name": "Expedia",
"url": "https://www.expedia.com/Cheap-Flights-To-Boston.d178239.Travel-Guide-Flights"
},
{
"type": "ai_overview",
"rank_group": 1,
"rank_absolute": 1,
"page": 1,
"position": "left",
"asynchronous_ai_overview": false,
"markdown": "The BMW M4 F82 is a high-performance coupe..."
}
]
}
]
}
]
}错误处理
建议根据顶层和任务级的 status_code、status_message 做统一异常处理。
- 错误码说明路径:
/v3/appendix/errors - 顶层
status_code表示整次请求是否成功; tasks[].status_code表示单个任务执行结果;- 即使 HTTP 请求成功,也应检查 JSON 中的状态码字段。
常见处理建议:
- 校验 HTTP 状态码;
- 再校验顶层
status_code是否为20000; - 遍历
tasks,检查每个任务的status_code; - 对参数错误、余额不足、频率限制、无效地区/语言等做重试或告警。
使用建议
- 如果只自然排名,建议设置较小的
depth,控制成本; - 如果需要做页面可见性分析、首屏占位评估,启用
calculate_rectangles=true; - 如果重点分析 AI Overview,建议结合
load_async_ai_overview=true; - 如果要持续追踪目标站点是否出现在结果中,可结合
target或stop_crawl_on_match; - 若要分析 PAA扩展层级,可使用
people_also_ask_click_depth。
实用场景
- 监控实时排名:抓取指定在不同地区、语言、设备下的自然结果与绝对排名,用于 SEO 日常监控和波动预警。
- 识别 SERP 特征占位:分析精选摘要、PAA、知识图谱、AI Overview、图片和视频等模块出现,评估真实点击空间。
- 评估品牌结构:统计品牌站点在
organic、paid、knowledge_graph、local_pack等模块中的出现位置,衡量页搜索占比。 - 定位竞品:通过
target、related_result、about_this_result等字段识别竞品落地页、同域扩展结果与来源策略。 - 计算首屏可见性:结合
calculate_rectangles返回的像素坐标,评估结果是否位于首屏、被哪些 SERP 模块挤压,为 SEO 与投放协同优化提供依据。