SeerMarTech API 文档

主题

Google 历史 SERP 实时查询 ​

接口概述 ​

/v3/dataforseo_labs/google/historical_serps/live 用于获取指定在指定地区、语言与时间范围采集到的 Google 历史搜索结果页（SERP）。

除常规自然结果外，本接口还会返回当期 SERP 中出现的精选摘要、知识图谱、People Also Ask、图片、视频、地图、本地、购物、AI Overview 等扩展结果，便于分析：

  • 排名随时间的变化趋势
  • SERP 版式变化
  • 特殊搜索结果的出现与消失
  • 竞争页面的历史

历史数据最长可追溯 12 个月。

请求信息 ​

  • 方法：POST
  • 地址：https://api.seermartech.cn/v3/dataforseo_labs/google/historical_serps/live
  • Content-Type：application/json
  • Authorization：Bearer smt_live_YOUR_KEY

计费与调用限制 ​

本接口按请求计费。

  • 参考价：以响应中的 cost 字段为准
  • 如需估算，可按成本（USD）换算为人民币；扣费以响应头 X-SeerMarTech-Charge-CNY 为准

调用限制：

  • 每分钟最多 2000 次 API 调用
  • 每次 Live SERP 调用 支持 1 个任务
  • 最大并发请求数 30

POST 请求体为 JSON 数组格式：[{ ... }]

请求参数 ​

任务参数 ​

字段类型填说明
keywordstring是，最长 700 个字符。%## 会被解码，+ 会被解码为空格；如需保留 %，请写为 %25；如需保留 +，请写为 %2B。
date_fromstring否时间范围开始日期，格式：yyyy-mm-dd。若不传，默认返回从当前 datetime 向前最多 365 天的历史 SERP。最早支持回溯到当前时间前 365 天。
date_tostring否时间范围结束日期，格式：yyyy-mm-dd。默认使用当天日期。示例：2021-09-01
location_namestring条件填地区完整名称。未传 location_code 时填。location_name 与 location_code 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区。示例：United Kingdom
location_codeinteger条件填地区唯一标识。未传 location_name 时填。location_name 与 location_code 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区编码。示例：2840
language_namestring条件填语言完整名称。未传 language_code 时填。language_name 与 language_code 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言。示例：English
language_codestring条件填语言唯一标识。未传 language_name 时填。language_name 与 language_code 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言编码。示例：en
tagstring否自定义任务标识，最长 255 个字符。可用于请求与结果匹，返回时会出现在响应的 data 对象中。

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_serps/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keyword": "albert einstein",
 "location_code": 2840,
 "language_code": "en",
 "date_from": "2021-08-01",
 "date_to": "2021-10-01"
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_serps/live"
payload = [
 {
 "keyword": "albert einstein",
 "location_name": "United States",
 "language_name": "English",
 "date_from": "2021-08-01",
 "date_to": "2021-10-01"
 }
]
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const payload = [
 {
 keyword: "albert einstein",
 location_code: 2840,
 language_code: "en",
 date_from: "2021-08-01",
 date_to: "2021-10-01"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_serps/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: payload
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应结构 ​

接口返回 JSON 编码结果，顶层 tasks 数组。

顶层响应字段 ​

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

tasks[] 字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态信息
timestring任务执行耗时
costfloat任务成本，单位 USD
result_countintegerresult 数组数量
patharrayURL 路径
dataobject回显请求参数
resultarray获取结果数组；按指定时间范围返回各月采集到的 SERP 数据

result[] 字段 ​

字段类型说明
se_typestring搜索引擎类型
keywordstring请求中的；返回时 %## 会被解码，+ 会被转为空格
location_codeinteger地区编码
language_codestring语言编码
total_countinteger数据库中与请求匹的结果总数
items_countinteger当前 items 返回数量
itemsarray命中的历史 SERP 结果

items[] 通用字段 ​

每个历史 SERP 记录通常以下字段：

字段类型说明
se_typestring搜索引擎类型
keywordstring
typestring结果类型
se_domainstring搜索引擎域名
location_codeinteger地区编码
language_codestring语言编码
check_urlstring直达搜索结果页 URL，可用于校验结果
datetimestring结果采集时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
spellobject搜索引擎自动纠错信息
item_typesarray当前 SERP 中出现的结果类型集合
se_results_countintegerSERP 总结果数
items_countintegeritems 数组中结果数量
itemsarray该次 SERP 中的结果项

spell 字段 ​

字段类型说明
keywordstring自动纠正后的
typestring纠错类型，可选：did_you_mean、showing_results_for、no_results_found_for

item_types 可选值 ​

可能出现的 SERP素类型：

answer_box、carousel、multi_carousel、featured_snippet、google_flights、google_reviews、google_posts、images、jobs、knowledge_graph、local_pack、hotels_pack、map、organic、paid、people_also_ask、related_searches、people_also_search、shopping、top_stories、twitter、video、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、ai_overview

主要结果类型字段说明 ​

由于本接口支持的 SERP素非常多，以下保留各主要类型的核心字段定义。返回中当前 SERP 出现的类型。

1) organic 自然结果 ​

字段类型说明
se_typestring搜索引擎类型
typestring固定为 organic
rank_groupinteger同类型分组排名
rank_absoluteintegerSERP 绝对排名
positionstring位置，left 或 right
xpathstring素 XPath
domainstring域名
titlestring标题
urlstringURL
breadcrumbstring面屑
is_imageboolean是否图片
is_videoboolean是否视频
is_featured_snippetboolean是否为精选摘要来源
is_maliciousboolean是否被标记为恶意
descriptionstring摘要描述
pre_snippetstring描述前附加信息
extended_snippetstring描述后附加信息
amp_versionboolean是否有 AMP 版本
ratingobject评分信息
highlightedarray描述中加粗词
linksarray站点链接
about_this_resultobject“此结果”面板信息
main_domainstring主域名
relative_urlstring相对 URL
etvfloat预估自然流量
estimated_paid_traffic_costfloat预估等价付费流量成本
rank_changesobject相比上月的排名变化
backlinks_infoobject排名页面/站点的外链信息
rank_infoobject页面与主域名权重信息

rating ​

字段类型说明
rating_typestring评分类型：Max5、Percents、CustomMax
valuefloat评分值
votes_countinteger评价数
rating_maxinteger满分值
字段类型说明
typestring固定为 link_element
titlestring站点链接标题
descriptionstring描述
urlstring站点链接 URL

about_this_result ​

字段类型说明
typestring固定为 about_this_result_element
urlstring结果 URL
sourcestring补信息来源
source_infostring附加说明
source_urlstring来源 URL
languagestring结果语言
locationstring结果地区
search_termsarray匹到的搜索词
related_termsarray搜索词

rank_changes ​

字段类型说明
previous_rank_absoluteinteger上月绝对排名；若为新结果则为 null
is_newboolean是否为新出现结果
is_upboolean是否上升
is_downboolean是否下降
字段类型说明
referring_domainsinteger引荐域名数，子域名分开计数
referring_main_domainsinteger主域名数
referring_pagesinteger引荐页面数
dofollowintegerdofollow 链接数
backlinksinteger总外链数
time_updatestring外链数据更新时间，UTC

rank_info ​

字段类型说明
page_rankinteger页面权重
main_domain_rankinteger主域名权重

2) paid 广告结果 ​

字段类型说明
typestring固定为 paid
rank_groupinteger同类型分组排名
rank_absoluteinteger绝对排名
positionstringleft / right
xpathstringXPath
titlestring标题
domainstring广告域名
descriptionstring描述
breadcrumbstring面屑
urlstring落地页 URL
highlightedarray加粗词
extraobject附加信息，如 ad_aclk
description_rowsarray扩展描述
linksarray广告站点链接
main_domainstring主域名
relative_urlstring相对 URL
etvfloat预估流量
estimated_paid_traffic_costfloat预估付费流量成本
rank_changesobject相比上月的排名变化

3) featured_snippet 精选摘要 ​

字段类型说明
typestring固定为 featured_snippet
rank_groupinteger分组排名
rank_absoluteinteger绝对排名
positionstringleft / right
xpathstringXPath
domainstring域名
titlestringSERP 标题
featured_titlestring来源页标题
descriptionstring摘要
urlstring来源 URL
tablearray/object摘要表格，可能为空
main_domainstring主域名
relative_urlstring相对 URL
etvfloat预估自然流量
estimated_paid_traffic_costfloat预估等价付费流量成本
rank_changesobject排名变化

4) ai_overview AI 概览 ​

字段类型说明
typestring固定为 ai_overview
rank_groupinteger分组排名
rank_absoluteinteger绝对排名
pageinteger所在搜索结果页码
positionstringleft / right
xpathstringXPath
asynchronous_ai_overviewboolean是否异步加载
markdownstringAI 概览的 Markdown 文本
itemsarrayAI 概览中的块
referencesarray参考来源
rectangleobject结果在 SERP 中的坐标和尺寸；若未启用计算则为 null

ai_overview 子类型 ​

  • ai_overview_element
  • ai_overview_video_element
  • ai_overview_table_element
  • ai_overview_expanded_element
  • ai_overview_reference

常见子字段 ​

字段类型说明
titlestring素标题
textstring文本
markdownstringMarkdown
linksarray链接列表
imagesarray图片列表
referencesarray引用来源
tableobject表格
componentsarray展开型组件

rectangle ​

字段类型说明
xfloat左上角 X 坐标
yfloat左上角 Y 坐标
widthfloat宽度，像素
heightfloat高度，像素

5) knowledge_graph 知识图谱 ​

字段类型说明
typestring固定为 knowledge_graph
rank_groupinteger分组排名
rank_absoluteinteger绝对排名
positionstringleft / right
xpathstringXPath
titlestring标题
sub_titlestring副标题
descriptionstring描述
card_idstring卡片 ID
urlstringURL
image_urlstring图片 URL
logo_urlstringLogo URL
cidstring客户端 ID
itemsarray知识图谱结构化条目

知识图谱中的 items 可能：

  • knowledge_graph_images_item
  • knowledge_graph_list_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

这些子类型可进一步：

  • link
  • links
  • items
  • expanded_element
  • table

6) 常见 SERP素 ​

以下类型同样可能出现在 items 中，返回字段与展示形态一致：

类型说明
carousel轮播结果
multi_carousel多组轮播结果
answer_box直接答案框
related_searches搜索
people_also_search用户还会搜索
people_also_ask用户还问了
local_pack本地商家结果
hotels_pack店结果
map地图结果
google_flights航班结果
google_reviewsGoogle 评论模块
google_postsGoogle 帖子模块
video视频结果
images图片结果
shopping购物结果
jobs职位结果
events活动结果
mention_carousel提及轮播
recipes菜谱结果
top_sights热门景点
top_stories热门新闻
twitter社交模块
scholarly_articles学术文章
popular_products热门商品
podcasts播客
questions_and_answers问答结果
find_results_on在站点查找结果
stocks_box股票卡片
visual_stories视觉
commercial_units商业卡片
local_services本地服务广告/服务
google_hotelsGoogle店模块
math_solver数学求解器

重要说明 ​

时间范围 ​

  • 历史数据可查询最近 12 个月
  • 若不传 date_from，默认从当前 datetime 往前最多取 365 天
  • 若不传 date_to，默认使用当天

解码规则 ​

  • keyword 返回时会解码 %##
  • + 会被视为空格
  • 如需保留字面 %，请传 %25
  • 如需保留字面 +，请传 %2B

排名变化说明 ​

rank_changes 以前一个月为基准计算，即使前一个月不在本次请求时间范围，也可能参与计算。

稳定性建议 ​

建议根据 /v3/appendix/errors 中的状态码设计异常处理与重试机制，：

  • 顶层 status_code
  • 任务级 tasks[].status_code

响应示例 ​

json
{
 "version": "0.1.20220216",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "23.9825 sec.",
 "cost": 0.0005,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "historical_serps",
 "se_type": "google",
 "keyword": "albert einstein",
 "language_name": "English",
 "location_code": 2840,
 "date_from": "2021-08-01",
 "date_to": "2021-10-01"
 },
 "result": [
 {
 "se_results_count": 85600000,
 "items_count": 96,
 "items": [
 {
 "type": "top_stories",
 "rank_group": 1,
 "rank_absolute": 3,
 "position": "left"
 },
 {
 "type": "answer_box",
 "rank_group": 1,
 "rank_absolute": 4,
 "position": "left"
 },
 {
 "type": "organic",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "left",
 "domain": "example.com",
 "title": "示例自然结果",
 "url": "https://example.com/",
 "breadcrumb": "https://example.com",
 "is_image": false,
 "is_video": false,
 "is_featured_snippet": false,
 "is_malicious": false,
 "description": "示例描述",
 "amp_version": false,
 "main_domain": "example.com",
 "relative_url": "/",
 "etv": 15.2,
 "estimated_paid_traffic_cost": 119.48,
 "rank_changes": {
 "previous_rank_absolute": 1,
 "is_new": false,
 "is_up": false,
 "is_down": false
 }
 },
 {
 "type": "featured_snippet",
 "rank_group": 1,
 "rank_absolute": 10,
 "position": "left",
 "domain": "www.rome.net",
 "title": "Rome Metro - Lines, hours, fares and Rome metro maps",
 "description": "Most important metro stations...",
 "url": "https://www.rome.net/metro"
 },
 {
 "type": "knowledge_graph",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "right",
 "title": "Eminem",
 "sub_title": "American rapper"
 },
 {
 "type": "ai_overview",
 "rank_group": 1,
 "rank_absolute": 1,
 "page": 1,
 "position": "left",
 "asynchronous_ai_overview": false,
 "markdown": "AI Overview 示例"
 }
 ]
 }
 ]
 }
 ]
}

错误码 ​

本接口使用统一状态码体系：

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

完整错误码与说明请参考：

  • /v3/appendix/errors

建议至少处理以下场景：

  • 参数缺失或格式错误 -出并发或频率限制
  • 账户余额不足
  • 平台采集失败或结果不可用
  • 临时性服务异常

实用场景 ​

  1. 追踪排名波动：按月回看目标的历史 SERP，识别网站排名上升、下降或新结果页的时间点。
  2. 分析 SERP 版式演化：统计某在不同月份出现的 featured_snippet、people_also_ask、ai_overview 等，评估自然点击空间变化。
  3. 监控竞争对手历史：提取历史自然结果与广告结果中的竞争域名，分析对手何时、退出或强化某类布局。
  4. 评估类型机会：根据历史 SERP 中图片、视频、问答、购物、新闻等模块的出现频率，判断更适合哪类生产。
  5. 复盘算法或市场事件影响：结合 rank_changes 与 SERP 特征变化，定位某月排名异常背后的页面竞争、结果结构变化或搜索意图迁移。

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

© 2026 SeerMarTech · GEO · SEO 营销数据 API