历史 SERP（Legacy）实时接口

GET /v3/dataforseo_labs/locations_and_languages

本接口使用 POST /v3/dataforseo_labs/historical_serps/live，用于查询指定、地区和时间范围采集的 Google 历史搜索结果页（SERP）。接口会返回每个月的 SERP 快，以及自然结果、广告、精选摘要、知识图谱、搜索、图片、商品、本地结果等扩展，便于分析排名和 SERP 结构随时间的变化。

> 容性说明：本页描述的是 Legacy 请求和响应结构。历史数据最早可追溯至 2021-08-01。如需使用新版结构，请参考新版历史 SERP 接口文档。

接口信息

项目	说明
请求方法	`POST`
请求路径	`/v3/dataforseo_labs/historical_serps/live`
完整 URL	`https://api.seermartech.cn/v3/dataforseo_labs/historical_serps/live`
请求格式	JSON 数组，UTF-8 编码
单次请求任务数	1
平台限流以认证说明中的 30/60/120 次/分钟规则为准
数据起始日期	`2021-08-01`

每个请求只能一个任务，因此请求体是一个对象的 JSON 数组：

json

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

计费

每次请求均会产生费用。参考价约 ¥0.0036 / 次。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

参数	类型	填	说明
`keyword`	string	是	要查询的，最长 700 个字符。参数中的 `%##` 编码会被解码，`+` 会被解码为空格。若中需要使用百分号 `%`，请编码为 `%25`；需要使用加号 `+`，请编码为 `%2B`。
`date_from`	string	否	时间范围起始日期，格式为 `yyyy-mm-dd`。未填写时，返回从 `2021-08-01` 起的历史 SERP。最早可填写 `2021-08-01`。
`date_to`	string	否	时间范围结束日期，格式为 `yyyy-mm-dd`。未填写时默认使用当前日期。示例：`2021-09-01`。
`location_name`	string	条件填	地区完整名称。未指定 `location_code` 时填。`location_name` 与 `location_code` 至少填写一个。
`location_code`	integer	条件填	地区唯一编码。未指定 `location_name` 时填。`location_name` 与 `location_code` 至少填写一个。
`language_name`	string	否	语言完整名称。填写后无需填写 `language_code`。不填写时，返回所有可用语言的结果。
`language_code`	string	否	语言编码。填写后无需填写 `language_name`。不填写时，返回所有可用语言的结果。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中，可用于匹请求和结果。

地区和语言列表可通过以下接口获取：

text

GET https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages

请求示例

cURL

bash

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

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/historical_serps/live"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "keyword": "albert einstein",
        "location_name": "United States",
        "language_name": "English",
        "date_from": "2021-08-01",
        "date_to": "2021-10-01",
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()

result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/dataforseo_labs/historical_serps/live",
  [
    {
      keyword: "albert einstein",
      location_code: 2840,
      language_code: "en",
      date_from: "2021-08-01",
      date_to: "2021-10-01",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

if (response.data.status_code === 20000) {
  console.log(response.data);
} else {
  console.error(
    `请求失败，错误码：${response.data.status_code}，消息：${response.data.status_message}`
  );
}

响应结构

响应为 JSON 对象，顶层 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用响应状态码。`20000` 表示成功。
`status_message`	string	通用状态消息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常在 `10000-60000` 范围。
`status_message`	string	任务状态消息。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求 URL 路径。
`data`	object	创建任务时提交的参数。
`result`	array	历史 SERP 结果数组。每个通常对应时间范围的一个月度 SERP 快。

`result`字段

字段	类型	说明
`keyword`	string	请求中的。返回时已对 `%##` 解码，`+` 会还原为空格。
`type`	string	搜索结果类型，通常为 `organic`。
`se_domain`	string	搜索引擎域名，例如 `google.com`。
`location_code`	integer	地区编码。
`language_code`	string	语言编码。
`check_url`	string	对应 SERP 的直接 URL，可用于核验结果准确性。
`datetime`	string	结果采集时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`spell`	object/null	搜索引擎自动纠错信息。
`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` 可选值

text

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素字段

多数 items素以下字段：

字段	类型	说明
`type`	string	SERP素类型。
`rank_group`	integer	同类型组的排名。不同类型不会计该字段。
`rank_absolute`	integer	素在整个 SERP 中的绝对排名。
`position`	string	素在页面中的位置，可取 `left` 或 `right`。
`xpath`	string	素在 SERP 页面中的 XPath。
`title`	string	素标题。
`description`	string	素描述或摘要。
`url`	string	素 URL。
`domain`	string	素所属域名。
`main_domain`	string	主域名。
`relative_url`	string	不协议和域名的相对 URL。
`highlighted`	array	描述中被突出显示的。
`etv`	float	预估流量，通常按点击率与搜索量的乘积估算。
`impressions_etv`	float	基于展示次数估算的流量。
`estimated_paid_traffic_cost`	float	将预估自然流量转化为付费搜索流量时的月度预估成本。
`rank_changes`	object	与前一个月相比的排名变化。

`rank_changes` 字段

字段	类型	说明
`previous_rank_absolute`	integer/null	上一个月的绝对排名。新出现的为 `null`。
`is_new`	boolean	前一个月是否不存在该。
`is_up`	boolean	排名是否上升。
`is_down`	boolean	排名是否下降。

排名变化即使请求的日期范围不前一个月，也可能基于系统已采集的前置数据计算。

主要 SERP素字段

不同 type 的会以下专属字段。未出现的字段通常不返回，或以 null 返回。

`organic`：自然结果

字段	类型	说明
`breadcrumb`	string	面屑路径。
`is_image`	boolean	是否图片。
`is_video`	boolean	是否视频。
`is_featured_snippet`	boolean	是否为精选摘要。
`is_malicious`	boolean	是否被标记为恶意结果。
`pre_snippet`	string	描述前附加的信息。
`extended_snippet`	string	描述后附加的信息。
`amp_version`	boolean	是否提供 AMP 版本。
`rating`	object	评分信息。
`links`	array/null	站点链接。
`about_this_result`	object	“此结果”信息。
`language`	string	结果语言。
`location`	string	结果适用地区。
`search_terms`	array	结果中匹的搜索词。
`related_terms`	array	搜索词。

rating 对象字段：

字段	类型	说明
`rating_type`	string	评分类型：`Max5`、`Percents` 或 `CustomMax`。
`value`	float/integer	评分值。
`votes_count`	integer	评价数量。
`rating_max`	integer	评分上限。

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

`paid`：付费广告

字段	类型	说明
`breadcrumb`	string	广告面屑。
`extra`	object	广告附加信息。
`extra.ad_aclk`	string	广告标识符。
`description_rows`	array/null	扩展描述行。
`links`	array/null	广告站点链接。
`main_domain`	string	主域名。
`relative_url`	string	相对 URL。
`etv`	float	预估流量。
`impressions_etv`	float	基于展示次数的预估流量。
`estimated_paid_traffic_cost`	float	付费流量月度预估成本。

`featured_snippet`：精选摘要

字段	类型	说明
`featured_title`	string	精选摘要来源页面标题。
`table`	array/null	摘要中的表格。
`table_header`	array	表格列名。
`table_content`	array	表格。
`main_domain`	string	主域名。
`relative_url`	string	相对 URL。
`etv`	float	预估流量。
`impressions_etv`	float	基于展示次数的预估流量。
`estimated_paid_traffic_cost`	float	付费流量月度预估成本。

`answer_box`：答案框

字段	类型	说明
`text`	array/null	答案文本。
`links`	array/null	答案框中的链接。

`carousel` 与 `multi_carousel`：轮播模块

字段 rank_group、rank_absolute、position、xpath 和 items。

carousel 子：

字段	类型	说明
`type`	string	固定为 `carousel_element`。
`title`	string	轮播项标题。
`sub_title`	string	轮播项副标题。

multi_carousel 子：

字段	类型	说明
`type`	string	`multi_carousel_element` 或 `multi_carousel_snippet`。
`title`	string	项目标题。
`multi_carousel_snippets`	array	多级轮播摘要。

`related_searches` 与 `people_also_search`

字段 rank_group、rank_absolute、position、xpath 和 items。

people_also_search 还可能：

字段	类型	说明
`title`	string	模块标题。
`items`	array	搜索项目。

`local_pack`：本地结果

字段	类型	说明
`title`	string	商家或地点名称。
`description`	string	商家描述。
`phone`	string	电话号码。
`url`	string	URL。
`is_paid`	boolean	是否为广告。
`rating`	object	商家评分。
`main_domain`	string	主域名。
`relative_url`	string	相对 URL。
`etv`	float	预估流量。
`impressions_etv`	float	基于展示次数的预估流量。
`estimated_paid_traffic_cost`	float	付费流量成本估算。

`hotels_pack`：结果

字段	类型	说明
`title`	string	店模块标题。
`date_from`	string	住日期，格式为 `yyyy-mm-dd`。
`date_to`	string	退房日期，格式为 `yyyy-mm-dd`。
`items`	array	店项目列表。

项目通常：

字段	类型	说明
`type`	string	固定为 `hotels_pack_element`。
`price`	object	指定日期的价格信息。
`title`	string	店名称。
`desription`	string	店描述。原字段名保持为 `desription`。
`hotel_identifier`	string	店唯一标识。
`domain`	string	域名。
`url`	string	URL。
`is_paid`	boolean	是否为广告。
`rating`	object	店评分。

`knowledge_graph`：知识图谱

字段：

text

title
sub_title
description
card_id
url
image_url
logo_url
cid
items

知识图谱中的子类型：

text

knowledge_graph_images_item
knowledge_graph_images_element
knowledge_graph_list_item
knowledge_graph_list_element
knowledge_graph_description_item
knowledge_graph_row_item
knowledge_graph_carousel_item
knowledge_graph_carousel_element
knowledge_graph_part_item
knowledge_graph_expanded_item
knowledge_graph_expanded_element
knowledge_graph_shopping_item
knowledge_graph_shopping_element

常见子字段如下：

字段	类型	说明
`data_attrid`	string	搜索引擎定义的数据属性 ID。
`text`	string	文本。
`link`	object	链接。
`links`	array	链接数组。
`image_url`	string	图片 URL。
`alt`	string	图片替代文本。
`sub_title`	string	副标题。
`items`	array	子项目列表。
`table`	object	表格。
`expanded_element`	array	展开的附加。
`featured_title`	string	来源页面标题。
`source`	string	来源。
`snippet`	string	链接或结果摘要。

知识图谱子中的 rank_group 和 rank_absolute 在桌面端通常为 0。

`top_stories`：热门资讯

字段	类型	说明
`items`	array	热门资讯项目。
`source`	string	资讯来源。
`domain`	string	来源域名。
`title`	string	资讯标题。
`date`	string	页面发布日期。
`amp_version`	boolean	是否提供 AMP 版本。
`timestamp`	string	发布时间，UTC 格式。
`url`	string	资讯 URL。

`twitter`：社交媒体结果

字段	类型	说明
`title`	string	模块标题。
`url`	string	模块 URL。
`items`	array	帖子列表。
`tweet`	string	帖子。
`date`	string	发布日期。
`timestamp`	string	发布时间，UTC 格式。

`google_flights`、`map` 与 `google_hotels`

这些通常：

字段	类型	说明
`title`	string	模块标题。
`url`	string	模块或项目 URL。
`items`	array	子项目。
`hotel_identifier`	string	`google_hotels` 中的唯一标识。

`google_reviews` 与 `google_posts`

google_reviews 字段：

字段	类型	说明
`reviews_count`	integer	评论总数。
`rating`	object	评分信息。
`place_id`	string	地点标识。
`feature`	string	附加特征标识。
`cid`	string	地点唯一客户端 ID。

google_posts 字段：

字段	类型	说明
`posts_id`	string	帖子功能标识。
`feature`	string	附加特征标识。
`cid`	string	地点唯一客户端 ID。

`video`：视频结果

字段	类型	说明
`items`	array	视频项目列表。
`source`	string	视频来源。
`title`	string	视频标题。
`timestamp`	string	发布时间，UTC 格式。
`url`	string	视频 URL。

`people_also_ask`：用户还问了

字段	类型	说明
`items`	array	问题列表。
`title`	string	问题标题。
`expanded_element`	array	展开后的答案。
`featured_title`	string	答案来源标题。
`url`	string	来源 URL。
`domain`	string	来源域名。
`description`	string	答案描述。
`timestamp`	string	结果发布时间。
`table`	object	答案中的表格。
`table_header`	array	表格列名。
`table_content`	array	表格。

`images`：图片结果

字段	类型	说明
`title`	string	图片模块标题。
`url`	string	图片搜索 URL。
`items`	array	图片列表。
`related_image_searches`	array/null	图片搜索。
`alt`	string	图片替代文本。
`image_url`	string	压缩图片或缩略图 URL。

`shopping`、`popular_products` 与 `commercial_units`

这些通常商品标题、描述、来源、商城信息和价格对象。

字段	类型	说明
`title`	string	商品或模块标题。
`description`	string	商品描述。
`price`	object	商品价格。
`source`	string	信息来源。
`marketplace`	string	商户或商城名称。
`marketplace_url`	string	商城 URL。
`rating`	object	商品评分。
`url`	string	商品 URL。

price 对象字段：

字段	类型	说明
`current`	float	当前价格。
`regular`	float	常规价格。
`max_value`	float	价格区间上限。
`currency`	string	ISO 货币编码。
`is_price_range`	boolean	是否为价格区间。
`displayed_price`	string	SERP 中原始展示的价格文本。

`jobs`：职位结果

字段	类型	说明
`title`	string	职位标题。
`description`	string	职位描述。
`author`	string	发布。
`job_posted_time`	string	职位发布时间描述。
`timestamp`	string	发布时间。
`contract_type`	string	合同类型。
`salary`	string	薪资信息。
`url`	string	职位 URL。

`events`：活动结果

字段	类型	说明
`title`	string	活动标题。
`description`	string	活动摘要。
`URL`	string	活动 URL。

> 注意：该的字段名为大写 URL，使用时应保持原样。

`mention_carousel`：提及轮播

字段	类型	说明
`items`	array	轮播项目。
`title`	string	项目标题。
`price`	object	项目价格。
`rating`	object	项目评分。
`mentioned_in`	array	项目出现的结果。

mentioned_in 中的链接通常 type、title、snippet 和 URL。

`recipes`：食谱结果

字段	类型	说明
`title`	string	食谱标题。
`url`	string	食谱 URL。
`domain`	string	来源域名。
`source`	string	信息来源。
`description`	string	食谱摘要。
`time`	string	准备和烹饪所需总时长。
`rating`	object	食谱评分。

`top_sights`：热门景点

字段	类型	说明
`title`	string	景点或模块标题。
`items`	array	景点项目。
`url`	string	景点 URL。
`description`	string	景点摘要。
`rating`	object	景点评分。

`scholarly_articles`：学术文章

字段	类型	说明
`title`	string	学术文章模块标题。
`url`	string	文章或搜索 URL。
`items`	array	学术文章列表。
`author`	string	。
`description`	string	文章摘要。

`podcasts`：播客结果

字段	类型	说明
`items`	array	播客项目。
`title`	string	播客或单集标题。
`url`	string	播客 URL。
`description`	string	播客摘要。
`timestamp`	string	单集添加时间。
`time_to_play`	string	单集播放总时长。

`questions_and_answers`：问答结果

字段	类型	说明
`items`	array	问答项目。
`url`	string	问答 URL。
`question_text`	string	问题文本。
`answer_text`	string	答案文本。
`source`	string	答案来源。
`domain`	string	来源域名。

`find_results_on`：在平台查找结果

字段	类型	说明
`items`	array	平台结果列表。
`title`	string	结果标题。
`domain`	string	来源域名。
`url`	string	结果 URL。
`source`	string	结果来源。

`stocks_box`：股票信息框

字段	类型	说明
`title`	string	股票信息框标题。
`source`	string	股票数据来源。
`snippet`	string	股票摘要。
`price`	object	抓取时展示的价格。
`url`	string	URL。
`domain`	string	域名。
`table`	object/null	股票数据表格。
`graph`	object	股票走势图数据。

graph 字段：

字段	类型	说明
`items`	array	当前时间段的数据点。
`previous_items`	array	前一时间段的收盘数据。
`type`	string	数据点类型，通常为 `graph_element`。
`date`	string	时间，ISO 8601 格式：`yyyy-mm-ddThh:mm:ss`。
`value`	float	对应时间点的价格。

`visual_stories`：视觉

字段	类型	说明
`items`	array	视觉项目。
`title`	string	事标题。
`url`	string	事 URL。
`domain`	string	来源域名。

`local_services`：本地服务

字段	类型	说明
`domain`	string	服务域名。
`items`	array	本地服务项目。
`title`	string	服务标题。
`url`	string	服务 URL。
`description`	string	服务描述。
`rating`	object	服务评分。
`image_url`	string	服务图片 URL。

`math_solver`：数学解题框

字段	类型	说明
`title`	string	数学题目标题。
`result`	string	计算结果。
`items`	array	解题步骤或附加。
`expanded_element`	array	展开的解题步骤。
`links`	array/null	链接。

解题步骤通常：

字段	类型	说明
`type`	string	`math_solver_element` 或 `math_solver_expanded_element`。
`title`	string	步骤标题。
`solution`	array	解题过程。

响应示例

以下为经过裁剪的响应示例，响应中的 items 会根据和地区返回不同的 SERP素。

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": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "23.9825 sec.",
      "cost": 0.0005,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "historical_serps",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "historical_serps",
        "keyword": "albert einstein",
        "language_code": "en",
        "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?q=albert%20einstein",
          "datetime": "2021-10-01 03:37:47 +00:00",
          "spell": null,
          "item_types": [
            "organic",
            "featured_snippet",
            "people_also_ask",
            "related_searches"
          ],
          "se_results_count": 2070000000,
          "items_count": 4,
          "items": [
            {
              "type": "organic",
              "rank_group": 1,
              "rank_absolute": 1,
              "position": "left",
              "xpath": "/html/body/div/div/div",
              "domain": "example.com",
              "title": "示例搜索结果",
              "url": "https://example.com/page",
              "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,
              "links": null,
              "main_domain": "example.com",
              "relative_url": "/page",
              "etv": 15.2,
              "impressions_etv": 24.44,
              "estimated_paid_traffic_cost": 119.48,
              "rank_changes": {
                "previous_rank_absolute": 2,
                "is_new": false,
                "is_up": true,
                "is_down": false
              }
            },
            {
              "type": "featured_snippet",
              "rank_group": 1,
              "rank_absolute": 2,
              "position": "left",
              "xpath": "/html/body/div/div/div/div",
              "domain": "example.org",
              "title": "示例精选摘要",
              "featured_title": "示例来源页面",
              "description": "精选摘要。",
              "url": "https://example.org/article",
              "table": null,
              "main_domain": "example.org",
              "relative_url": "/article",
              "etv": 10.5,
              "impressions_etv": 18.2,
              "estimated_paid_traffic_cost": 80.4,
              "rank_changes": {
                "previous_rank_absolute": null,
                "is_new": true,
                "is_up": false,
                "is_down": false
              }
            },
            {
              "type": "people_also_ask",
              "rank_group": 1,
              "rank_absolute": 3,
              "position": "left",
              "xpath": "/html/body/div/div/div/div",
              "items": [
                {
                  "type": "people_also_ask_element",
                  "title": "示例问题",
                  "xpath": "/html/body/div/div/div/div"
                }
              ]
            },
            {
              "type": "related_searches",
              "rank_group": 1,
              "rank_absolute": 4,
              "position": "left",
              "xpath": "/html/body/div/div/div/div",
              "items": []
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

接口会在顶层和任务级别分别返回 status_code 与 status_message。应用程序应同时检查：

HTTP 状态码；
顶层 status_code；
每个任务的 status_code；
tasks_error 是否大于 0。

20000 表示请求成功。状态码表示参数错误、认证失败、频率限制、任务处理失败或服务异常。生产环境应针对错误码实现重试、告警和失败任务记录机制。

实用场景

追踪月度排名：按、地区和语言拉取历史 SERP，识别排名上升、下降和新结果页的页面，评估 SEO 优化效果。
分析 SERP 功能占位：统计精选摘要、问答框、图片、购物、本地和知识图谱等的出现，指导结构和富媒体标记优化。
监测竞争对手可见度：按月对比竞争域名在自然结果、广告和特殊 SERP 模块中的排名变化，定位竞争对手增长或流失的。
评估本地 SEO 表现：结合 local_pack、google_reviews 和 local_services 数据，比较不同地区的本地排名、评分和评论覆盖。
建立历史 SERP 变化看板：利用 rank_changes、item_types、etv 和 impressions_etv 构建排名与预估流量趋势，为 SEO 报告和预算分提供依据。

历史 SERP（Legacy）实时接口 ​

接口信息 ​

计费 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 字段 ​

result字段 ​

spell 字段 ​

item_types 可选值 ​

SERP素字段 ​

rank_changes 字段 ​

主要 SERP素字段 ​

organic：自然结果 ​

paid：付费广告 ​

featured_snippet：精选摘要 ​

answer_box：答案框 ​

carousel 与 multi_carousel：轮播模块 ​

related_searches 与 people_also_search ​

local_pack：本地结果 ​

hotels_pack：结果 ​

knowledge_graph：知识图谱 ​

top_stories：热门资讯 ​

twitter：社交媒体结果 ​

google_flights、map 与 google_hotels ​

google_reviews 与 google_posts ​

video：视频结果 ​

历史 SERP（Legacy）实时接口

接口信息

计费

请求参数

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

`tasks` 字段

`result`字段

`spell` 字段

`item_types` 可选值

SERP素字段

`rank_changes` 字段

主要 SERP素字段

`organic`：自然结果

`paid`：付费广告

`featured_snippet`：精选摘要

`answer_box`：答案框

`carousel` 与 `multi_carousel`：轮播模块

`related_searches` 与 `people_also_search`

`local_pack`：本地结果

`hotels_pack`：结果

`knowledge_graph`：知识图谱

`top_stories`：热门资讯

`twitter`：社交媒体结果

`google_flights`、`map` 与 `google_hotels`

`google_reviews` 与 `google_posts`

`video`：视频结果