Skip to content

实时高级自然搜索结果接口

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。

请求参数

主要参数

字段类型说明
keywordstring查询,最长 700 个字符。字段中的 %## 会被解码,+ 会被解码为空格;如需保留 %,请写为 %25;如需保留 +,请写为 %2B。若 allinanchor:allintext:allintitle:allinurl:cache:define:definition:filetype:id:inanchor:info:intext:intitle:inurl:link:site: 等搜索运算符,费用将按 5 倍计。
location_codeinteger条件填搜索地区编码。当未提供 location_namelocation_coordinate 时填。提供该字段后,无需再传 location_name / location_coordinate。可通过 /v3/serp/google/locations 获取可用地区编码。示例:2840
language_codestring搜索语言编码。若已提供 language_name 可不传。提供该字段后,无需再传 language_name。可通过 /v3/serp/google/languages 获取可用语言编码。示例:en
depthinteger抓取深度,即返回的 SERP 结果数量。默认 10,最大 200。 10 条时可能产生额外费用。
devicestring设备类型,可选:desktopmobile。默认 desktop
load_async_ai_overviewboolean是否加载异步 AI Overview。设为 true 时,即使该为异步加载,也会尝试获取;设为 false 时返回缓存中可获得的 ai_overview。默认 false。启用会产生额外费用。若响应中该不存在或 asynchronous_ai_overview=false,额外费用会返还。

附加参数

字段类型说明
location_namestring条件填搜索地区名。当未提供 location_codelocation_coordinate 时填。示例:London,England,United Kingdom
language_namestring搜索语言名。示例:English
osstring设备操作系统。device=desktop 时可选 windowsmacos,默认 windowsdevice=mobile 时可选 androidios,默认 android
tagstring用户自定义任务标识,最长 255 字符。会原样出现在响应的 data 对象中。
stop_crawl_on_matcharray命中目标即停止爬取。最多支持 10 个目标对象,每个对象 match_typematch_value。响应将返回直到匹目标为止的结果。按爬取范围计费。
match_typestring条件填当设置 stop_crawl_on_match 时填。可选:domain(指定域名/子域名)、with_subdomains(主域名及子域名)、wildcard(通符模式)。
match_valuestring条件填当设置 stop_crawl_on_match 时填。填写目标域名、子域名或通值,不要带协议头。示例:"match_value": "example.com""match_value": "/blog/post-*"
max_crawl_pagesinteger最多爬取多少页搜索结果,最大 100。每页按 10 个自然结果计费。与 depth 决定抓取范围。
search_paramstring额外搜索参数。部分参数不支持,若传将被自动忽略:lrcras_qdras_sitesearchas_occtas_filetype
remove_from_urlarray从结果 URL 中移除特定参数,最多 10 个。若同时设置 target,会移除这些参数再执行匹。
people_also_ask_click_depthinteger展开 people_also_ask 的点击层级,用于获取更多 people_also_ask_element。取值范围 1-4。每次点击有额外费用,未发生的点击费用会返还。
group_organic_resultsboolean是否将同域结果作为主自然结果的 related_result 返回。默认 true。设为 false 时,related_result 会作为独立 organic 结果返回。
calculate_rectanglesboolean是否计算 SERP素的像素位置和尺寸。默认 false。启用后会返回 rectangle 对象,并产生额外费用。
browser_screen_widthinteger浏览器屏幕宽度,范围 240-9999。在 calculate_rectangles=true 时生效。默认:桌面 1920,Android 手机 360,iOS 手机 375
browser_screen_heightinteger浏览器屏幕高度,范围 240-9999。在 calculate_rectangles=true 时生效。默认:桌面 1080,Android 手机 640,iOS 手机 812
browser_screen_resolution_ratiointeger屏幕分辨率比,范围 0.5-3。在 calculate_rectangles=true 时生效。默认:桌面 1,Android/iOS 手机 3
urlstring直接传搜索 URL,由本接口自动解析为查询参数。该方式处理难度最高,且要求 URL 中已准确语言和地区信息,通常不建议使用。URL 中若不支持的搜索参数,也会被自动忽略。
location_coordinatestringGPS 定位参数,格式为 "latitude,longitude,radius"。纬度和经度最多 7 位小数;radius 范围 199-199999(毫米)。示例:53.476225,-2.243572,200
se_domainstring搜索引擎域名。通常系统会根据地区和语言自动选择,也可手动指定,例如 google.co.ukgoogle.com.augoogle.de
targetstring只返回特定目标域名、子域名或网页 URL 的 SERP素。域名/子域名不要带 https://www.。支持通符 *
target_search_modestring多目标匹停止模式。需与 stop_crawl_on_match 一起使用。可选:allany,默认 anyall 表示所有目标都命中才停止;any 表示命中任一目标即停止。
find_targets_inarray指定在哪些 SERP素类型中检查目标匹。需与 stop_crawl_on_match 一起使用。若不传,则默认检查所有 urldomain 的一级。不可与 ignore_targets_in含相同类型。
ignore_targets_inarray指定在哪些 SERP素类型中忽略目标匹。需与 stop_crawl_on_match 一起使用。不可与 find_targets_in含相同类型。

target 支持的匹示例

写法含义
example.com匹站点首页,例如 https://example.comhttps://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 可选值

  • organic
  • paid
  • local_pack
  • featured_snippet
  • events
  • google_flights
  • images
  • jobs
  • knowledge_graph
  • local_service
  • map
  • scholarly_articles
  • third_party_reviews
  • twitter

请求示例

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 数组。

顶层字段

字段类型说明
versionstringAPI 当前版本
status_codeinteger通用状态码,完整列表见 /v3/appendix/errors
status_messagestring通用状态信息
timestring执行耗时,单位秒
costfloat本次请求总成本,单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务结果数组

任务级字段

字段类型说明
idstring任务 ID,UUID 格式
status_codeinteger任务状态码
status_messagestring任务状态信息
timestring任务执行耗时
costfloat单任务成本,单位 USD
result_countintegerresult 数组数
patharrayURL 路径
dataobject原始请求参数回显
resultarray结果数组

结果级通用字段

字段类型说明
keywordstring请求,返回时 %## 会被解码,+ 会被转为空格
typestring搜索类型
se_domainstring搜索引擎域名
location_codeinteger地区编码
language_codestring语言编码
check_urlstring搜索结果直链,可用于人工校验
datetimestring结果抓取时间,UTC 格式:yyyy-mm-dd hh-mm-ss +00:00
spellobject搜索引擎自动纠错信息
refinement_chipsobject搜索建议筛选项
item_typesarray本次 SERP 中出现的类型集合
se_results_countintegerSERP 结果总量
pages_countinteger实抓取的 SERP 页数
items_countintegeritems 数组中的数量
itemsarraySERP素数组

spell 字段

字段类型说明
keywordstring搜索引擎纠错后的
typestring纠错类型:did_you_meanshowing_results_forno_results_found_forincluding_results_for

refinement_chips 字段

字段类型说明
typestring固定为 refinement_chips
xpathstring素 XPath
itemsarray筛选项列表

refinement_chips.items[]

字段类型说明
typestring固定为 refinement_chips_element
titlestring筛选项标题
urlstring筛选后的搜索 URL
domainstringSERP 中域名
optionsarray进一步筛选选项

主要 SERP素说明

由于高级 SERP 返回的类型非常多,下面保留最核心、最常用且最业务价值的字段结构。响应中还可能出现更多类型,字段命名与结构保持容。

1) organic 自然结果

字段类型说明
typestring固定为 organic
rank_groupinteger同类型中的组排名
rank_absoluteinteger整个 SERP 中的绝对排名
pageinteger所在搜索结果页码
positionstring版位位置:left / right
xpathstring素 XPath
domainstring域名
titlestring标题
urlstring目标 URL
cache_urlstring缓存页 URL
related_search_urlstring站点搜索 URL
breadcrumbstring面屑
website_namestring网站名称
is_imageboolean是否带图
is_videoboolean是否带视频
is_featured_snippetboolean是否为精选摘要来源
is_maliciousboolean是否被标记为恶意站点
is_web_storyboolean是否为 Web Story
descriptionstring摘要描述
pre_snippetstring描述前附加信息
extended_snippetstring描述后附加信息
imagesarray图片列表
amp_versionboolean是否有 AMP 版本
ratingobject评分信息
priceobject价格信息
highlightedarray描述中加粗词
linksarray站点链接(sitelinks)
faqobjectFAQ 扩展,已废弃,固定返回 null
extended_people_also_searcharray返回搜索结果页后出现的搜索扩展
about_this_resultobject“此结果”面板信息
related_resultarray同域结果
timestampstring结果发布时间
rectangleobject像素坐标信息;在 calculate_rectangles=true 时返回

rating

字段类型说明
rating_typestring评分类型:Max5PercentsCustomMax
valuefloat评分值
votes_countinteger评论/评分数量
rating_maxinteger评分上限

price

字段类型说明
currentfloat当前价格
regularfloat原价
max_valuefloat最高价格
currencystring货币 ISO 代码
is_price_rangeboolean是否为区间价格
displayed_pricestring搜索结果中原始价格文本

about_this_result

字段类型说明
typestring固定为 about_this_result_element
urlstring结果 URL
sourcestring信息来源
source_infostring来源描述
source_urlstring来源页 URL
languagestring结果语言
locationstring结果适用地区
search_termsarray命中的搜索词
related_termsarray

rectangle

字段类型说明
xinteger左上角横坐标
yinteger左上角纵坐标
widthinteger素宽度(像素)
heightinteger素高度(像素)

2) paid 付费结果

核心字段与 organic 类似,常用补字段:

字段类型说明
website_namestring广告主网站名称
extra.ad_aclkstring广告标识符
description_rowsarray扩展描述行
linksarray广告附加链接
priceobject价格信息
ratingobject评分信息
rectangleobject像素坐标信息

字段类型说明
typestring固定为 featured_snippet
domainstring来源域名
titlestring结果标题
featured_titlestring精选摘要来源页标题
descriptionstring摘要
timestampstring发布时间
urlstring来源 URL
imagesarray图片
tableobject表格型摘要数据
rectangleobject像素坐标信息

4) people_also_ask 大家还会问

字段类型说明
typestring固定为 people_also_ask
itemsarray问题列表
rectangleobject像素坐标信息

people_also_ask.items[]

字段类型说明
typestring固定为 people_also_ask_element
titlestring问题标题
seed_questionstring触发扩展问题的原始问题
xpathstring素 XPath
expanded_elementarray展开后的答案

当设置 people_also_ask_click_depth 时,可获得更多扩展问题及答案。


5) knowledge_graph 知识图谱

字段类型说明
typestring固定为 knowledge_graph
titlestring实体名称
subtitlestring副标题/实体类别
descriptionstring实体简介
card_idstring卡片 ID
urlstring官方或主要链接
image_urlstring主图
logo_urlstringLogo
cidstring实体 CID
itemsarray图谱子
rectangleobject像素坐标信息

知识图谱可能多种子项:

  • knowledge_graph_images_item
  • knowledge_graph_list_item
  • knowledge_graph_ai_overview_item
  • knowledge_graph_description_item
  • knowledge_graph_row_item
  • knowledge_graph_carousel_item
  • knowledge_graph_part_item
  • knowledge_graph_expanded_item
  • knowledge_graph_shopping_item
  • knowledge_graph_hotels_booking_item

这些子项通常标题、链接、图片、文本、表格、引用、价格、日期、矩形坐标等结构化数据。


6) ai_overview AI 概览

字段类型说明
typestring固定为 ai_overview
rank_groupinteger组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstring位置:left / right
xpathstring素 XPath
asynchronous_ai_overviewboolean是否为异步加载
markdownstringAI Overview 的 Markdown
itemsarray概览子项
referencesarray引用来源
rectangleobject像素坐标信息

ai_overview.items[] 常见类型:

  • ai_overview_element:文本主体
  • ai_overview_video_element:视频片段
  • ai_overview_table_element:表格
  • ai_overview_expanded_element:可展开扩展

ai_overview_reference 常见字段:

字段类型说明
sourcestring引用来源名称
domainstring引用域名
urlstring引用页面 URL
titlestring引用页面标题
textstring被引用的文本片段

7) 常见 SERP素类型

响应中的 items 还可能以下类型:

  • answer_box
  • carousel
  • multi_carousel
  • related_searches
  • people_also_search
  • local_pack
  • hotels_pack
  • top_stories
  • twitter
  • map
  • google_flights
  • google_reviews
  • third_party_reviews
  • google_posts
  • video
  • app
  • images
  • shopping
  • jobs
  • events
  • mention_carousel
  • recipes
  • top_sights
  • scholarly_articles
  • popular_products
  • podcasts
  • questions_and_answers
  • find_results_on
  • stocks_box
  • visual_stories
  • commercial_units
  • local_services
  • google_hotels
  • math_solver
  • currency_box
  • courses
  • product_considerations
  • short_videos
  • found_on_web
  • refine_products
  • explore_brands
  • perspectives
  • discussions_and_forums
  • compare_sites

这些通常以下通用字段:

  • type
  • rank_group
  • rank_absolute
  • page
  • position
  • xpath
  • title
  • url
  • domain
  • items
  • rating
  • price
  • timestamp
  • rectangle

响应示例

以下为根据示例整理后的精简版响应保留结构,便于理解。

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_codestatus_message 做统一异常处理。

  • 错误码说明路径:/v3/appendix/errors
  • 顶层 status_code 表示整次请求是否成功;
  • tasks[].status_code 表示单个任务执行结果;
  • 即使 HTTP 请求成功,也应检查 JSON 中的状态码字段。

常见处理建议:

  1. 校验 HTTP 状态码;
  2. 再校验顶层 status_code 是否为 20000
  3. 遍历 tasks,检查每个任务的 status_code
  4. 对参数错误、余额不足、频率限制、无效地区/语言等做重试或告警。

使用建议

  • 如果只自然排名,建议设置较小的 depth,控制成本;
  • 如果需要做页面可见性分析、首屏占位评估,启用 calculate_rectangles=true
  • 如果重点分析 AI Overview,建议结合 load_async_ai_overview=true
  • 如果要持续追踪目标站点是否出现在结果中,可结合 targetstop_crawl_on_match
  • 若要分析 PAA扩展层级,可使用 people_also_ask_click_depth

实用场景

  • 监控实时排名:抓取指定在不同地区、语言、设备下的自然结果与绝对排名,用于 SEO 日常监控和波动预警。
  • 识别 SERP 特征占位:分析精选摘要、PAA、知识图谱、AI Overview、图片和视频等模块出现,评估真实点击空间。
  • 评估品牌结构:统计品牌站点在 organicpaidknowledge_graphlocal_pack 等模块中的出现位置,衡量页搜索占比。
  • 定位竞品:通过 targetrelated_resultabout_this_result 等字段识别竞品落地页、同域扩展结果与来源策略。
  • 计算首屏可见性:结合 calculate_rectangles 返回的像素坐标,评估结果是否位于首屏、被哪些 SERP 模块挤压,为 SEO 与投放协同优化提供依据。

统一入口:官网 · LLM API · 控制台