SERP 实时自然结果查询

接口概述

该接口用于实时获取指定关键词、搜索引擎、地域和语言下的搜索结果页（SERP）数据。

• 实时返回结果，无需创建任务再轮询
• 单次请求支持提交 1 个任务
• 每分钟最多可发起 2000 次调用
• POST 请求体为 UTF-8 编码的 JSON 数组格式：[{ ... }]

请求地址

POST https://api.seermartech.cn/v3/serp/wp/organic/live/regular

说明：原文中示例路径存在 v2 与 organic 表述不一致的。本文保留容路径写法时，以原始技术路径 /v3/... 为准；接前请以返回和控制台联调结果确认最终使用路径。

计费说明

本接口按请求计费。

• 参考价需根据游返回动态计算
• 扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 响应中的 cost 为原始计费金额；如按对外参考口径换算， 参考价约 ¥0.0480 / 次

若使用以下高级搜索运算符，单任务费用会放大 5 倍：

allinanchor:、allintext:、allintitle:、allinurl:、cache:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、site:

此外：

• depth过 10 时，如果搜索引擎返回 10 条结果，可能产生额外费用
• max_crawl_pages 按抓取页数计费，每页通常对应 10 条自然结果
• 使用 stop_crawl_on_match 时，会对抓取到命中条件前的每个 SERP 页面计费

请求参数

主要参数

字段名	类型	填	说明
keyword	string	是	，最长 700 个字符。字段中的 %## 会被解码，+ 会被解码为空格。若需保留 %，请写为 %25；若需保留 +，请写为 %2B。若中特定高级搜索运算符，费用按 5 倍计算。
location_code	integer	条件填	搜索地域编码。当未提供 location_name 或 location_coordinate 时填。提供该字段后，无需再传 location_name / location_coordinate。示例：2840
language_code	string	条件填	搜索语言编码。当未提供 language_name 时填。提供该字段后，无需再传 language_name。示例：en
depth	integer	否	解析深度，即返回的结果数量。默认 10，最大 200。 10 可能触发额外计费。
device	string	否	设备类型。可选：desktop、mobile。默认：desktop

附加参数

字段名	类型	填	说明
location_name	string	条件填	搜索地域完整名称。当未提供 location_code 或 location_coordinate 时填。示例：London,England,United Kingdom
language_name	string	条件填	搜索语言完整名称。当未提供 language_code 时填。示例：English
os	string	否	设备操作系统。device=desktop 时可选 windows、macos，默认 windows；device=mobile 时可选 android、ios，默认 android
tag	string	否	自定义任务标识，最长 255 字符。可用于请求和结果对账，响应 data 中会返回该值
stop_crawl_on_match	array	否	命中目标后停止抓取的规则数组，最多 10 个对象。响应将返回截至命中 match_value 的结果
match_type	string	条件填	当设置 stop_crawl_on_match 时填。可选：domain、with_subdomains、wildcard
match_value	string	条件填	当设置 stop_crawl_on_match 时填。目标域名、子域名或通模式。域名不可带协议头。示例："example.com"、"/blog/post-*"
max_crawl_pages	integer	否	最大抓取结果页数，最大 100。每抓取一页都会计费
search_param	string	否	搜索查询附加参数。以下参数不支持，若传会被自动忽略：lr、cr、as_qdr、as_sitesearch、as_occt、as_filetype
group_organic_results	boolean	否	是否将结果归并到父自然结果中。true：作为父结果片段返回；false：作为独立自然结果返回。默认 true
url	string	否	直接传搜索 URL。系统会自动拆解为所需字段。该方式处理复杂，且要求 URL 中已精确指定语言与地域，通常不建议优使用
location_coordinate	string	条件填	GPS 定位，格式：latitude,longitude,radius。当未提供 location_name 或 location_code 时填。纬度和经度最多 7 位小数；radius 取值范围 199 到 199999（毫米）。示例：53.476225,-2.243572,200
se_domain	string	否	搜索引擎域名。通常系统会根据语言和地域自动选择，也可手动指定，如：google.co.uk、google.com.au、google.de
target	string	否	返回匹指定目标域名、子域名或页面的 SERP素。域名/子域名不要带 https:// 和 www.。支持 * 通
target_search_mode	string	否	多目标匹停止策略。启用前提：已设置 stop_crawl_on_match。可选：all、any，默认 any
find_targets_in	array	否	指定在哪些 SERP素类型中查找目标。启用前提：已设置 stop_crawl_on_match
ignore_targets_in	array	否	指定在哪些 SERP素类型中忽略目标查找。启用前提：已设置 stop_crawl_on_match

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

注意：find_targets_in 与 ignore_targets_in 不能相同类型。

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/wp/v2/live/regular" \
--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/regular"
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/regular",
 [
 {
 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	通用状态码
status_message	string	通用状态信息
time	string	执行耗时，单位秒
cost	float	请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数
tasks_error	integer	返回错误的任务数
tasks	array	任务结果数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一 ID，UUID 格式
status_code	integer	任务状态码
status_message	string	任务状态说明
time	string	任务执行耗时
cost	float	任务费用，单位 USD
result_count	integer	result 数组中的结果数
path	array	请求路径
data	object	回显请求参数
result	array	获取结果

result[] 字段

字段名	类型	说明
keyword	string	POST 中传的。返回时 %## 会被解码，+ 会被解码为空格
type	string	请求中的搜索类型
se_domain	string	搜索引擎域名
location_code	integer	地域编码
language_code	string	语言编码
check_url	string	搜索结果直达 URL，可用于人工核验结果
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	已抓取的结果页数
items_count	integer	items 中返回的结果数量
items	array	结果项数组

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	进一步细化选项

options[] 字段：

字段名	类型	说明
type	string	固定为 refinement_chips_option
title	string	选项标题
url	string	带细化参数的搜索 URL
domain	string	SERP 中的域名

返回的结果类型说明

item_types 可能以下类型：

• answer_box
• app
• carousel
• multi_carousel
• featured_snippet
• google_flights
• google_reviews
• images
• jobs
• knowledge_graph
• local_pack
• map
• organic
• paid
• people_also_ask
• related_searches
• people_also_search
• shopping
• top_stories
• twitter
• video
• events
• mention_carousel
• ai_overview

注意：该接口虽然会在 item_types 中标识 SERP出现过的结果类型，但完整返回的数据覆盖 featured_snippet、organic、paid。 如果需要获取更多 SERP 特性与富结果明细，请使用对应的高级 SERP 接口。

items[] 结果项字段

featured_snippet

字段名	类型	说明
type	string	固定为 featured_snippet
rank_group	integer	同类型结果组排名
rank_absolute	integer	SERP 中绝对排名
page	integer	所在搜索结果页码
domain	string	结果域名
title	string	标题
description	string	描述
url	string	结果 URL
breadcrumb	string	始终为 null

organic

字段名	类型	说明
type	string	固定为 organic
rank_group	integer	同类型结果组排名
rank_absolute	integer	SERP 中绝对排名
page	integer	所在搜索结果页码
domain	string	结果域名
title	string	标题
description	string	描述
url	string	结果 URL
breadcrumb	string	面屑路径

paid

字段名	类型	说明
type	string	固定为 paid
rank_group	integer	同类型结果组排名
rank_absolute	integer	SERP 中绝对排名
page	integer	所在搜索结果页码
domain	string	广告域名
title	string	广告标题
description	string	广告描述
url	string	广告链接
breadcrumb	string	广告面屑路径

说明：rank_absolute 按返回结果中的顺序递增，但不某些高级 SERP 特性在的完整量位置。如果你需要所有 SERP素及完整位次，请使用相应高级接口。

响应示例

{
 "version": "0.1.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "12.2397 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": "flight ticket new york san francisco",
 "tag": "tag2",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "item_types": [],
 "se_results_count": 85600000,
 "pages_count": 1,
 "items_count": 96,
 "items": []
 }
 ]
 }
 ]
}

错误处理

请务基于 status_code 和 status_message 设计异常处理逻辑：

• 顶层请求失败
• 单任务失败
• 参数缺失或格式错误
• 频控限
• 目标搜索引擎侧异常

完整错误码体系请参考：/v3/appendix/errors

使用说明与注意事项

1. 单次请求只能提交一个任务 虽然请求体是数组格式，但 Live SERP 每次调用 1 个任务对象。

2. 会自动解码 返回结果中的 keyword 会对 %## 做解码，+ 也会被转为空格。

3. 不建议优使用 url 字段 直接传搜索 URL 虽然灵活，但解析复杂，对语言和地域要求严格，稳定性不如结构化参数方式。

4. target 对带 URL 的 SERP素生效 设置目标过滤时返回 url 字段的结果项。

5. find_targets_in 与 ignore_targets_in 互斥部分不可重复 同一种 SERP素类型不能同时出现在两个数组中。

实用场景

• 监控品牌词排名：实时抓取品牌词或核心产品词的自然结果和广告结果，快速发现官网排名波动与竞品抢位。
• 分析竞品投放覆盖：通过 paid 结果识别竞品广告出现的、落地页和展示文案，搜索投放优化。
• 定位目标站点收录表现：结合 target 或 stop_crawl_on_match，快速判断指定域名是否前几页结果，提升排名巡检效率。
• 评估多地域搜索差异：切换 location_code、language_code、device，比较不同国家、语言和设备下的 SERP 差异，支持化 SEO 策略制定。
• 捕捉精选摘要机会：识别 featured_snippet 出现的及当前占位页面，为重构和摘要位争夺提供依据。