历史 SERP（旧版）实时查询

POST /v3/dataforseo_labs/historical_serps/live

接口说明

注意：本接口文档对应旧版 Historical SERPs 结构。自 2022-03-19 起，平台 API 已更新请求与响应结构，但当前旧版接口仍持续容。若需使用新版结构，请参考对应新版文档。

该接口用于获取指定时间范围采集到的 Google SERP 历史结果。除常规搜索结果外，还会返回精选摘要（featured snippet）及 SERP 扩展的完整概览，适合用于分析指定在特定地区中的历史排名变化和页面特征演变。

历史数据最早可追溯至 2021-08-01。

• 请求方式：POST
• 请求地址：https://api.seermartech.cn/v3/dataforseo_labs/historical_serps/live
• 请求体格式：application/json
• 请求体结构：JSON 数组 [{ ... }]
• 频率限制：最高 2000 次 API 调用/分钟
• Live 接口限制：每次调用只能 1 个任务

计费说明

该接口按请求计费。

根据示例响应中的费用，本接口参考价约 ¥0.0080 / 次。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

以下字段用于设置任务：

字段名	类型	说明
keyword	string	，填。最多支持 700 个字符。请求中的 %## 会被解码，+ 会被解码为空格；如需保留 %，请写为 %25；如需保留 +，请写为 %2B。
date_from	string	起始日期，可选。不传时默认返回自 2021-08-01 起的已采集 SERP。最小值：2021-08-01。格式：yyyy-mm-dd。
date_to	string	结束日期，可选。不传时默认使用当天日期。格式：yyyy-mm-dd。例如：2021-09-01。
location_name	string	地区名。若未传 location_code，则该字段填。location_name 与 location_code 二选一传。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区。示例：United Kingdom
location_code	integer	地区唯一标识。若未传 location_name，则该字段填。location_name 与 location_code 二选一传。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区编码。示例：2840
language_name	string	语言名，可选。传该字段时可不传 language_code。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言。若忽略该字段，则返回所有可用语言结果。示例：English
language_code	string	语言代码，可选。传该字段时可不传 language_name。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言代码。若忽略该字段，则返回所有可用语言结果。示例：en
tag	string	自定义任务标识，可选，最多 255 个字符。可用于在响应中识别任务，对应值会出现在响应的 data 对象中。

响应结构

接口返回 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	任务结果数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表见 /v3/appendix/errors
status_message	string	任务状态消息
time	string	任务执行耗时
cost	float	该任务费用，单位 USD
result_count	integer	result 数组中的结果数量
path	array	URL 路径
data	object	与请求中传参数一致
result	array	获取结果数组

结果说明

result 数组中指定时间范围各月份采集到的 SERP 数据对象。

result[] 通用字段

字段名	类型	说明
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	搜索引擎自动纠错信息
item_types	array	当前 SERP 中出现的结果类型列表
se_results_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

item_types 可能值

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

---

主要 SERP素字段

由于本接口会返回大量 SERP素类型，以下按类型归纳核心字段。所有通常都以下基础字段：

• type：类型
• rank_group：同类型排名
• rank_absolute：SERP 绝对排名
• position：展示位置，通常为 left 或 right
• xpath： XPath

1）organic 自然结果

字段名	类型	说明
domain	string	结果域名
title	string	标题
url	string	落地页 URL
breadcrumb	string	面屑
is_image	boolean	是否图片
is_video	boolean	是否视频
is_featured_snippet	boolean	是否为精选摘要来源
is_malicious	boolean	是否被标记为恶意结果
description	string	描述文本
pre_snippet	string	描述前附加信息
extended_snippet	string	描述后附加信息
amp_version	boolean	是否存在 AMP 版本
rating	object	评分信息
highlighted	array	描述中加粗的
links	array	子链接（sitelinks）
about_this_result	object	“此结果”面板信息
main_domain	string	主域名
relative_url	string	相对 URL
etv	float	预估自然流量
impressions_etv	float	基于展示量的预估流量
estimated_paid_traffic_cost	float	将该自然流量换算为付费流量的预估成本
rank_changes	object	相比上月的排名变化

rating 字段

字段名	类型	说明
rating_type	string	评分类型：Max5、Percents、CustomMax
value	float	评分值
votes_count	integer	评论/投票数
rating_max	integer	评分上限

links[] 字段

字段名	类型	说明
type	string	固定为 link_element
title	string	子链接标题
description	string	子链接描述
url	string	子链接 URL

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	搜索词

rank_changes 字段

字段名	类型	说明
previous_rank_absolute	integer	上月绝对排名；若为新结果则为 null
is_new	boolean	是否为新出现
is_up	boolean	排名是否上升
is_down	boolean	排名是否下降

说明：rank_changes 即使请求中未上一个月，仍会基于前一个月的数据计算变化。

2）paid 付费广告结果

核心字段与 organic 类似，额外：

字段名	类型	说明
extra	object	额外广告信息
ad_aclk	string	广告标识
description_rows	array	扩展描述，若无则为 null

links[]类型为 ad_link_element。

3）featured_snippet 精选摘要

字段名	类型	说明
domain	string	结果域名
title	string	结果标题
featured_title	string	精选摘要来源页标题
description	string	摘要描述
url	string	结果 URL
table	array/object	摘要中的表格数据，若无则为 null
main_domain	string	主域名
relative_url	string	相对 URL
etv	float	预估自然流量
impressions_etv	float	基于展示量的预估流量
estimated_paid_traffic_cost	float	对应付费流量成本估算
rank_changes	object	排名变化

4）people_also_ask 提问

字段名	类型	说明
items	array	提问项列表

items[] 中类型为 people_also_ask_element，常见字段：

• title：问题标题
• xpath：XPath
• expanded_element：展开后的答案

expanded_element[] 中类型为 people_also_ask_expanded_element，常见字段：

• featured_title
• url
• domain
• title
• description
• timestamp
• table

5）knowledge_graph 知识图谱

桌面端知识图谱支持较复杂的嵌套结构，顶层常见字段如下：

字段名	类型	说明
title	string	标题
sub_title	string	副标题
description	string	描述
card_id	string	卡片 ID
url	string	URL
image_url	string	图片 URL
logo_url	string	Logo URL
cid	string	Google 定义的客户端 ID
items	array	知识图谱列表

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

常见子字段：

• title
• sub_title
• text
• data_attrid
• url
• domain
• image_url
• snippet
• table_header
• table_content

6）local_pack 本地结果

字段名	类型	说明
title	string	商户名称
description	string	描述
domain	string	域名
phone	string	电话
url	string	链接
is_paid	boolean	是否广告
rating	object	评分
main_domain	string	主域名
relative_url	string	相对 URL
etv	float	预估自然流量
impressions_etv	float	基于展示量的预估流量
estimated_paid_traffic_cost	float	付费流量成本估算
rank_changes	object	排名变化

7）媒体与聚合类

以下通常返回 items 数组，描述卡片：

• top_stories
• twitter
• video
• images
• shopping
• jobs
• events
• mention_carousel
• recipes
• top_sights
• scholarly_articles
• popular_products
• podcasts
• questions_and_answers
• find_results_on
• visual_stories
• commercial_units
• local_services

各自常见字段示例：

top_stories_element

• source
• domain
• title
• date
• amp_version
• timestamp
• url

twitter_element

• tweet
• date
• timestamp
• url

video_element

• source
• title
• timestamp
• url

images_element

• alt
• url
• image_url

shopping_element

• title
• price
• source
• description
• marketplace
• marketplace_url
• url

jobs_element

• title
• description
• author
• job_posted_time
• timestamp
• contract_type
• salary
• url

events_element

• title
• description
• URL

recipes_element

• title
• url
• domain
• source
• description
• time
• rating

popular_products_element

• title
• description
• price
• rating

podcasts_element

• title
• url
• description
• timestamp
• time_to_play

questions_and_answers_element

• url
• question_text
• answer_text
• source
• domain

find_results_on_element

• title
• domain
• url
• source

commercial_units_element

• title
• url
• domain
• price
• source
• rating

local_services_element

• title
• url
• domain
• description
• rating
• image_url

8）特殊

carousel

• title
• items[]：carousel_element
• title
• sub_title

multi_carousel

• items[]：multi_carousel_element
• title
• multi_carousel_snippets[]

answer_box

• text
• links[]

related_searches

• items

people_also_search

• title
• items

map

• title
• url

google_flights

• title
• url
• items[]
• description
• url

google_reviews

• reviews_count
• rating
• place_id
• feature
• cid

google_posts

• posts_id
• feature
• cid

hotels_pack

• title
• date_from
• date_to
• items[]：hotels_pack_element
• price
• title
• desription
• hotel_identifier
• domain
• url
• is_paid
• rating

google_hotels

• hotel_identifier
• url

stocks_box

• title
• source
• snippet
• price
• url
• domain
• table
• graph

graph 中：

• items[]：当前周期图表点
• previous_items[]：上一周期收盘图表点

图表点字段：

• type：graph_element
• date：ISO 8601 时间
• value：价格值

math_solver

• title
• result
• items[]：math_solver_element
• title
• expanded_element[]
• title
• solution
• links[]

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/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

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/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

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/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);
 });

响应示例

以下为基于原始文档整理后的示意性响应结构，字段已保留核心含义，部分长嵌套做了省略。

{
 "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",
 "keyword": "albert einstein",
 "language_name": "English",
 "location_code": 2840,
 "date_from": "2021-08-01",
 "date_to": "2021-10-01"
 },
 "result": [
 {
 "keyword": "albert einstein",
 "type": "organic",
 "se_domain": "google.com",
 "location_code": 2840,
 "language_code": "en",
 "check_url": "https://www.google.com/search?...",
 "datetime": "2021-10-01 03:37:47 +00:00",
 "spell": null,
 "item_types": [
 "organic",
 "featured_snippet",
 "people_also_ask",
 "top_stories"
 ],
 "se_results_count": 2070000000,
 "items_count": 106,
 "items": [
 {
 "type": "organic",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "left",
 "xpath": "/html/body/...",
 "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": "示例描述",
 "pre_snippet": null,
 "extended_snippet": null,
 "amp_version": false,
 "rating": null,
 "highlighted": [],
 "links": [],
 "about_this_result": {
 "type": "about_this_result_element",
 "url": "https://example.com/",
 "source": null,
 "source_info": null,
 "source_url": null,
 "language": "English",
 "location": "the United States",
 "search_terms": [],
 "related_terms": null
 },
 "main_domain": "example.com",
 "relative_url": "/",
 "etv": 15.2,
 "impressions_etv": 24.4416,
 "estimated_paid_traffic_cost": 119.4809,
 "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",
 "xpath": "/html/body/...",
 "domain": "www.rome.net",
 "title": "Rome Metro - Lines, hours, fares and Rome metro maps",
 "featured_title": null,
 "description": "精选摘要描述示例",
 "url": "https://www.rome.net/metro",
 "table": {
 "table_header": [],
 "table_content": []
 }
 },
 {
 "type": "people_also_ask",
 "rank_group": 1,
 "rank_absolute": 17,
 "position": "left",
 "xpath": "/html/body/...",
 "items": [
 {
 "type": "people_also_ask_element",
 "title": "What is the best free texting app?",
 "xpath": "/html/body/...",
 "expanded_element": []
 }
 ]
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示本次 API 请求整体状态
• tasks[].status_code 表示任务状态
• 建议同时处理 HTTP 状态码、顶层状态码和任务状态码
• 完整错误码与状态消息请参考：/v3/appendix/errors

建议重点处理以下异常场景：

1. 请求参数缺失或格式错误
2. location_name / location_code 未按要求提供
3. 日期出支持范围或格式错误
4. 访问频率限
5. 单次 Live 请求 1 个任务
6. 鉴权失败或账户余额不足

使用建议

1. 若要稳定分析排名趋势，建议固定 location_code 与 language_code
2. 若做月度对比，可按自然月设置 date_from、date_to
3. 若重点 SERP 特征占位，建议结合 item_types 与 items[].type 分析
4. 若要验证返回结果，可使用 check_url 进行抽样核验
5. 排名变化建议结合 rank_changes 字段直接读取，无需自行计算上月差值

实用场景

• 监控历史排名变化：按月份回溯指定在目标地区的 SERP 排名波动，识别流量下滑或增长拐点。
• 分析 SERP 特征占位：统计精选摘要、People Also Ask、本地、视频等在历史周期中的出现，评估自然点击空间变化。
• 识别竞品演变：提取历史 organic、paid、shopping 结果中的域名与标题，跟踪竞品在同一下的长期策略。
• 评估改版效果：对比上线前后的历史 SERP 结果及 rank_changes，验证页面优化是否带来排名提升。
• 挖掘本地与品牌结果机会：针对 local_pack、knowledge_graph、google_reviews 等做历史观察，判断品牌词或门店词的优化优级。