Google 历史数据库完整数据

GET /v3/dataforseo_labs/locations_and_languages

本接口路径为 /v3/databases/google/history/full。原始页面未单独声明 HTTP 方法；请以当前接口版本返回的接口定义为准。接口返回统一搜索历史 Google 数据库，数据格式支持 JSON。

该数据库由以下两部分组成：

历史 SERP 数据库：大量按月保存的 Google 搜索结果页快，并记录精选摘要、知识图谱、“用户还问了”、热门、购物结果、本地结果等 SERP 特征。
历史数据库：及历史搜索量、竞争度、每次点击费用等指标。

数据范围说明：

历史数据自 2021-09-01 起提供。
历史 SERP 数据提供最近 365 天 的记录。
返回数据支持 JSON 格式。
可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区和语言代码。

认证

请求时使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求地址

text

https://api.seermartech.cn/v3/databases/google/history/full

请求示例

> 原始页面未提供完整请求参数示例。以下展示标准请求格式，筛选字段请以接口版本为准。

cURL

bash

curl --request POST \
  --url https://api.seermartech.cn/v3/databases/google/history/full \
  --header 'Authorization: Bearer smt_live_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "location_code": 2840
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/databases/google/history/full"

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

# 请求体是 JSON 数组
payload = [
    {
        "location_code": 2840
    }
]

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

data = response.json()
print(data)

TypeScript

typescript

const response = await fetch(
  "https://api.seermartech.cn/v3/databases/google/history/full",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    // 请求体是 JSON 数组
    body: JSON.stringify([
      {
        location_code: 2840,
      },
    ]),
  },
);

if (!response.ok) {
  throw new Error(`请求失败：${response.status}`);
}

const data = await response.json();
console.log(data);

计费

费用取决于数据库的规模及地区参数。参考价以当前账户及请求条件为准。

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

地区和语言代码

可通过以下接口查询可用地区及语言：

http

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

常见示例：

字段	示例值	含义
`location`	`2840`	美国地区代码
`language`	`en`	英语语言代码

数据结构概览

返回结果以为基本单位。每个对象通常以下字段：

字段	类型	说明
`keyword`	string	，使用 UTF-8 编码
`location`	integer	地区代码
`language`	string	语言代码
`spell`	string \| null	搜索引擎自动纠正后的
`spell_type`	string \| null	自动纠正类型
`keyword_info_history`	object	按月份组织的历史指标
`serp_info_history`	object	按月份组织的历史 SERP 数据
`extra`	object	附加信息
`search_intent_info`	object	搜索意图信息

spell_type 可能的值：

did_you_mean
showing_results_for
no_results_found_for
including_results_for

历史数据

keyword_info_history 是一个对象，键名为 YYYYMM 格式的月份，例如 202109。

字段	类型	说明
`search_volume`	integer	平均月搜索量
`cpc`	float	历史平均每次点击费用，原始数据以 USD 指标表示
`competition`	float	付费搜索竞争度，取值范围为 `0` 至 `1`
`competition_level`	string \| null	付费搜索竞争等级：`LOW`、`MEDIUM`、`HIGH`
`low_top_of_page_bid`	float \| null	广告展示在首页顶部所需的较低出价估计
`high_top_of_page_bid`	float \| null	广告展示在首页顶部所需的较高出价估计
`time_update`	string	指标更新时间，ISO 8601 格式
`categories`	array	产品和服务类别
`history`	object	过去约四年的月度搜索量

说明：

search_volume 表示目标地区下的近似搜索次数。
cpc 基于广告顶部展示出价数据估算，不代表单独提供的广告平台 CPC 原始字段。
low_top_of_page_bid 和 high_top_of_page_bid 可能随请求地区变化。
history 的键为月份，值为对应月份的估算搜索量。

示例：

json

{
  "202109": {
    "search_volume": 1300,
    "cpc": 0.422711,
    "competition": 1,
    "competition_level": null,
    "low_top_of_page_bid": null,
    "high_top_of_page_bid": null,
    "time_update": "2021-10-12T18:29:11.9262890Z",
    "categories": [],
    "history": {
      "202101": 590,
      "202102": 720,
      "202103": 1000,
      "202104": 1600,
      "202105": 2400,
      "202106": 2900,
      "202107": 2400,
      "202108": 1900,
      "202109": 1000
    }
  }
}

历史 SERP 数据

serp_info_history 按月份保存 SERP 快，每个月对应一个独立对象。

字段	类型	说明
`check_url`	string	对应搜索结果页的直接 URL，可用于核对结果
`items_count`	integer	`serp` 数组中的结果数量
`keyword_difficulty`	integer \| null	难度，范围为 `0` 至 `100`
`se_results_count`	integer	SERP 中的结果总数
`time_update`	string	当前 SERP 数据更新时间
`previous_updated_time`	string \| null	上一次 SERP 数据更新时间
`item_types`	array	当前 SERP 中出现的结果类型
`serp`	array	SERP素

`keyword_difficulty`

该指标用于估算前十名自然结果的难度，取值范围为 0 至 100。数值越高，通常表示竞争越激烈。该指标综合分析 SERP 前十名页面的链接概况等因素。

`item_types`

item_types 记录 SERP 中出现的类型，可能：

text

answer_box
carousel
multi_carousel
featured_snippet
google_flights
google_reviews
google_posts
google_hotels
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
math_solver
currency_box
product_considerations
short_videos
refine_products
explore_brands
perspectives
discussions_and_forums
compare_sites
third_party_reviews
ai_overview

SERP 通用字段

大多数 SERP素会以下排名和流量字段：

字段	类型	说明
`type`	string	SERP素类型
`position`	string	素在 SERP 中的对齐方式，可为 `left` 或 `right`
`xpath`	string	素在页面中的 XPath
`traffic_cost`	float	将估算自然流量换算为付费流量后的月度成本估计
`rank_group`	integer	同类型中的分组排名
`rank_absolute`	integer	所有 SERP素中的绝对排名
`etv`	float	估算月自然流量
`is_new`	boolean	相比上一版本数据库是否为新增
`is_up`	boolean	相比上一版本数据库排名是否上升
`is_down`	boolean	相比上一版本数据库排名是否下降
`previous_rank_absolute`	integer	上一版本数据库中的绝对排名

：

rank_group 只在相同 type 的之间计算。
不同 type素之间不会计同一 rank_group。
etv 通常根据点击率和搜索量估算。
traffic_cost 通常根据 etv 与付费 cpc 估算。

自然结果 `organic`

自然结果通常以下字段：

字段	类型	说明
`title`	string	搜索结果标题
`pre_snippet`	string	结果描述前的附加文本
`description`	string	结果描述
`breadcrumb`	string	面屑路径
`url`	string	绝对 URL
`relative_url`	string	相对 URL
`domain`	string	结果域名
`main_domain`	string	去除子域名后的主域名
`images`	array \| null	结果图片
`highlighted`	array	描述中被突出显示的词语
`links`	array \| null	站点链接
`faq`	object \| null	常见问题扩展
`cache_url`	string \| null	页面缓存地址
`price`	object \| null	结果中的价格信息
`is_malicious`	boolean	是否被标记为恶意页面
`amp_version`	boolean	是否存在 AMP 版本
`is_image`	boolean	结果是否图片
`is_video`	boolean	结果是否视频
`is_featured_snippet`	boolean	是否为精选摘要
`extended_snippet`	string \| null	结果描述后的附加文本
`about_this_result`	object \| null	“此结果”信息
`rank_info`	object	页面和域名排名信息
`related_result`	array \| null	同域名结果
`related_search_url`	string \| null	搜索地址

`rating`

评分对象用于描述结果在 SERP 中展示的评价信息：

字段	类型	说明
`rating_type`	string	评分类型，可为 `Max5`、`Percents` 或 `CustomMax`
`value`	integer \| float	评分值
`votes_count`	integer	评价数量
`rating_max`	integer	当前评分类型的最大值

`price`

价格对象可能：

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

`about_this_result`

字段	类型	说明
`type`	string	通常为 `about_this_result_element`
`url`	string	结果 URL
`source`	string	附加信息来源
`source_info`	string	来源补说明
`source_url`	string	来源页
`language`	string	结果语言
`location`	string	结果地区
`search_terms`	array	结果中匹的搜索词
`related_terms`	array	结果中的词
`timestamp`	string	结果发布时间

`rank_info`

字段	类型	说明
`page_rank`	integer	页面排名指标
`main_domain_rank`	integer	主域名排名指标

付费结果 `paid`

付费结果通常：

字段	类型	说明
`title`	string	广告标题
`domain`	string	广告展示的完整域名
`main_domain`	string	主域名
`description`	string	广告描述
`breadcrumb`	string	广告面屑
`url`	string	广告目标绝对 URL
`relative_url`	string	广告目标相对 URL
`highlighted`	array	描述中突出显示的词语
`extra`	object	广告附加信息
`description_rows`	array \| null	扩展描述
`links`	array \| null	广告站点链接
`price`	object \| null	商品或服务价格
`is_new`	boolean	是否为新增
`is_up`	boolean	排名是否上升
`is_down`	boolean	排名是否下降
`previous_rank_absolute`	integer	上一次绝对排名

extra 中的 ad_aclk 为广告标识符。

常见 SERP 特征字段

`featured_snippet`

精选摘要字段：

title：结果标题。
featured_title：精选摘要来源页面标题。
description：摘要。
table：表格。
domain、main_domain：来源域名。
url、relative_url：来源地址。
images：摘要中的图片。
timestamp：结果发布时间。
rank_info：页面和域名排名信息。
is_new、is_up、is_down、previous_rank_absolute：与上一版本的变化信息。

`answer_box`

答案框字段：

text：答案文本数组。
links：答案框中的链接。
position、xpath：页面位置。
traffic_cost、rank_group、rank_absolute、etv：排名和流量估算字段。

`people_also_ask`

“用户还问了”字段：

items：问题列表。
title：问题标题。
seed_question：触发扩展结果的初始问题。
expanded_element：展开后的问题答案。
table：答案中的表格。
images：答案中的图片。
links：答案中的链接。
references：AI 摘要引用的页面。
asynchronous_ai_overview：AI 摘要是否异步加载。

`knowledge_graph`

知识图谱字段：

title：知识图谱标题。
subtitle：副标题。
description：描述信息。
card_id：知识图谱卡片 ID。
url：地址。
logo_url：图标地址。
items：知识图谱条目。
position、xpath：页面位置。
traffic_cost、rank_group、rank_absolute、etv：排名和流量估算字段。

知识图谱条目可能使用以下类型：

text

knowledge_graph_carousel_item
knowledge_graph_description_item
knowledge_graph_list_item
knowledge_graph_row_item
knowledge_graph_part_item
knowledge_graph_expanded_item
knowledge_graph_shopping_item
knowledge_graph_images_item
knowledge_graph_ai_overview_item

常见字段：

title、subtitle、text
link、links
items
image_url
domain
data_attrid
expanded_element
table
references

`carousel` 与 `multi_carousel`

轮播模块字段：

title：模块标题。
items：轮播项目。
subtitle：项目副标题。
multi_carousel_snippets：多层轮播摘要。
position、xpath：模块位置。
traffic_cost、rank_group、rank_absolute、etv：排名和流量估算字段。

`images`

图片结果字段：

title：图片模块标题。
url：图片搜索地址或结果地址。
items：图片项目。
alt：图片替代文本。
image_url：图片地址。
related_image_searches：图片搜索。
position、xpath、traffic_cost、rank_group、rank_absolute、etv：排名和流量估算字段。

`shopping` 与 `popular_products`

购物结果可能：

title：商品标题。
snippet 或 description：商品描述。
price：商品价格。
source：信息来源。
seller：商品卖家。
more_sellers：是否存在多个卖家。
marketplace：商品所在电商平台。
marketplace_url：电商平台地址。
rating：商品评分。
items：商品项目。

`local_pack` 与 `local_services`

本地结果可能：

title：商家或服务标题。
description：商家描述。
phone：电话号码。
booking_url：预约地址。
domain、main_domain、url、relative_url：商家地址信息。
is_paid：是否为广告。
rating：商家评分。
profile_image_url：商家头像或图片。
position、xpath、traffic_cost、rank_group、rank_absolute、etv：排名和流量估算字段。

`top_stories`

热门字段：

items：新闻项目。
source：信息来源。
domain：来源域名。
title：新闻标题。
date：页面发布日期。
timestamp：结果时间。
url：新闻地址。
image_url：图地址。
amp_version：是否存在 AMP 版本。
badges：结果徽章。

`video` 与 `short_videos`

视频结果可能：

title：视频标题。
snippet：视频摘要。
url：视频地址。
domain：视频所在域名。
source：视频来源。
image_url：缩略图地址。
date：发布日期或索引日期。
timestamp：发布时间或索引时间。
items：视频列表。

`jobs`

职位结果可能：

title：职位标题。
description：职位摘要。
author：发布。
job_posted_time：发布时间。
contract_type：合同类型。
salary：薪资信息。
url：职位地址。
timestamp：结果时间。

`events`

活动结果可能：

title：活动模块或活动标题。
snippet：活动摘要。
url：活动地址。
items：活动列表。
position、xpath、traffic_cost、rank_group、rank_absolute、etv：排名和流量估算字段。

`recipes`、`top_sights` 与 `scholarly_articles`

这些模块通常使用以下字段：

title：条目标题。
url：条目地址。
domain：来源域名。
source：信息来源。
description：摘要。
author：部分学术结果提供。
time：菜谱准备时间。
rating：评分。
items：条目列表。

`google_flights`、`hotels_pack` 与 `google_hotels`

结果可能：

title：模块标题。
date_from：或出发日期。
date_to：离店或返程日期。
items：航班或项目。
hotel_identifier：唯一标识。
url：结果地址。
price：价格信息。
rating：评分。
is_paid：是否为广告。

date_from 和 date_to 使用 YYYY-MM-DD 格式。

`twitter`

社交字段：

title：结果标题。
url：社交地址。
items：列表。
tweet：帖子文本。
date：发布日期。
timestamp：发布时间。

`questions_and_answers`

问答结果字段：

url：问答地址。
question_text：问题文本。
answer_text：答案文本。
source：答案来源。
votes：投票数。
items：问答列表。

`mention_carousel`

提及轮播字段：

title：模块标题。
items：被提及的商品或实体。
price：价格。
rating：评分。
mentioned_in：提及来源。
position、xpath、traffic_cost、rank_group、rank_absolute、etv：排名和流量估算字段。

`stocks_box`

股票信息字段：

title：股票模块标题。
source：数据来源。
snippet：股票摘要。
price：抓取时的价格。
url：地址。
domain：来源域名。
table：股票表格。
graph：价格曲线数据。
position、xpath、traffic_cost、rank_group、rank_absolute、etv：排名和流量估算字段。

graph.items 中的曲线点：

字段	类型	说明
`type`	string	通常为 `graph_element`
`date`	string	时间，ISO 8601 格式
`value`	integer \| float	对应时间的价格或汇率

股票价格可能存在延迟，不能作为实时依据。

`currency_box`

汇率转换结果字段：

value：转换数值。
converted_value：转换后的数值。
currency：原始货币。
converted_currency：目标货币。
timestamp：结果时间。
table：汇率表格。
graph：汇率曲线。
position、xpath、traffic_cost、rank_group、rank_absolute、etv：排名和流量估算字段。

`math_solver`

数学计算结果字段：

title：的数学表达式。
result：计算结果。
items：解题步骤。
expanded_element：展开步骤。
solution：计算过程。

`product_considerations`

产品购买参考字段：

title：购买参考模块标题。
items：产品考量项目。
consideration_category：考量类别。
expanded_element：展开后的产品信息。
breadcrumb：来源页面路径。
snippet：来源摘要。
domain、url：来源地址。
related_searches：搜索。
about_this_result：结果补信息。
references：AI引用来源。

`refine_products`、`explore_brands` 与 `compare_sites`

这些模块用于展示商品筛选、品牌探索或站点对比信息，常见字段：

title
url
domain
description
image_url
keyword
refine_type
source
items
position
xpath
traffic_cost
rank_group
rank_absolute
etv

`perspectives` 与 `discussions_and_forums`

观点及论坛结果可能：

title：模块或结果标题。
description：结果描述。
url：来源地址。
domain：来源域名。
source：来源名称。
date：发布日期或相对时间。
timestamp：结果时间。
posts_count：论坛帖子数量。
items：结果列表。

`third_party_reviews`

第三方评价模块字段：

reviews_count：评价数量。
title：评价来源名称。
url：评价来源地址。
rating：评分信息。
position、xpath、rank_group、rank_absolute：页面位置和排名信息。

AI 摘要字段

部分 SERP 结果可能 ai_overview 或扩展。

`ai_overview`

字段	类型	说明
`type`	string	通常为 `ai_overview`
`asynchronous_ai_overview`	boolean	是否异步加载
`markdown`	string	Markdown 格式的摘要
`items`	array	摘要项目
`references`	array	生成摘要时使用的参考页面
`position`	string	页面位置
`traffic_cost`	float	流量成本估算
`rank_group`	integer	分组排名
`rank_absolute`	integer	绝对排名
`etv`	float	估算流量

摘要可能出现以下类型：

text

ai_overview_element
ai_overview_video_element
ai_overview_table_element
ai_overview_expanded_element
ai_overview_expanded_component
ai_overview_reference
images_element
link_element

常见字段：

title：摘要标题。
text：摘要文本。
markdown：Markdown 格式。
links：摘要中的网页链接。
images：摘要中的图片。
videos：摘要中的视频。
table：摘要中的表格。
components：展开摘要中的组成部分。
references：引用来源。

引用对象通常：

字段	类型	说明
`type`	string	通常为 `ai_overview_reference`
`source`	string	引用来源名称或标题
`domain`	string	引用域名
`url`	string	引用页面 URL
`title`	string	引用页面标题
`text`	string	用于生成摘要的页面文本片段

附加信息

`extra`

extra 提供层面的补数据：

字段	类型	说明
`core_keyword`	string \| null	同组中的核心
`synonym_clustering_algorithm`	string \| null	同义词聚类算法
`detected_language`	string \| null	系统识别出的语言
`keyword_difficulty`	integer \| null	难度，范围为 `0` 至 `100`

synonym_clustering_algorithm 可能的值：

keyword_metrics：基于指标聚类。
text_processing：基于文本处理聚类。
null：没有识别到符合条件的同义词。

`search_intent_info`

字段	类型	说明
`main_intent`	string	主要搜索意图
`foreign_intent`	array	可能的搜索意图
`last_updated_time`	string	搜索意图数据更新时间

搜索意图可能的值：

text

informational
navigational
commercial
transactional

响应示例

以下示例展示型数据结构。响应中的 serp素会根据、地区和月份返回不同的 SERP 类型。

json

{
  "keyword": "coleman xtreme 5 cooler",
  "location": 2840,
  "language": "en",
  "spell": null,
  "spell_type": null,
  "keyword_info_history": {
    "202109": {
      "search_volume": 1300,
      "cpc": 0.422711,
      "competition": 1,
      "competition_level": null,
      "low_top_of_page_bid": null,
      "high_top_of_page_bid": null,
      "time_update": "2021-10-12T18:29:11.9262890Z",
      "categories": [],
      "history": {
        "202101": 590,
        "202102": 720,
        "202103": 1000,
        "202104": 1600,
        "202105": 2400,
        "202106": 2900,
        "202107": 2400,
        "202108": 1900,
        "202109": 1000
      }
    }
  },
  "serp_info_history": {
    "202109": {
      "check_url": "https://www.google.com/search?q=coleman%20xtreme%205%20cooler",
      "items_count": 100,
      "keyword_difficulty": null,
      "se_results_count": 2080000,
      "time_update": "2021-09-28T16:21:09.1487610Z",
      "previous_updated_time": null,
      "item_types": [
        "organic",
        "people_also_ask",
        "shopping",
        "images"
      ],
      "serp": [
        {
          "title": "70 Quart Xtreme 5 Cooler",
          "description": "Food and drinks last longer at the campsite or tailgate.",
          "domain": "www.example.com",
          "main_domain": "example.com",
          "url": "https://www.example.com/product",
          "relative_url": "/product",
          "type": "organic",
          "is_new": false,
          "is_up": false,
          "is_down": false,
          "previous_rank_absolute": 2,
          "position": "left",
          "xpath": "/html/body/div/div",
          "traffic_cost": 213.3822,
          "rank_group": 1,
          "rank_absolute": 2,
          "etv": 486.4
        },
        {
          "type": "people_also_ask",
          "items": [
            {
              "type": "people_also_ask_element",
              "title": "How many quarts is the cooler?",
              "seed_question": null,
              "expanded_element": []
            }
          ],
          "position": "left",
          "xpath": "/html/body/div/div/div",
          "traffic_cost": 0,
          "rank_group": 1,
          "rank_absolute": 4,
          "etv": 486.4
        }
      ]
    }
  },
  "extra": {
    "core_keyword": null,
    "synonym_clustering_algorithm": null,
    "detected_language": "en",
    "keyword_difficulty": 23
  },
  "search_intent_info": {
    "main_intent": "commercial",
    "foreign_intent": [],
    "last_updated_time": "2023-03-04T13:56:18.6047890Z"
  }
}

> 原始示例中的部分数组和对象存在格式截断或空值占位问题，例如 categories: ,、serp: ,。 JSON 响应中应使用合法的数组、对象、字符串或 null 值。

实用场景

回溯搜索量和竞争度变化，识别季节性需求与长期增长词，为排期和预算分提供依据。
对比不同月份的 SERP 结果和排名变化，定位竞争对手上升、下降或新首页的页面，支持竞品监控。
统计触发的 SERP 特征类型，发现精选摘要、知识图谱、购物、本地结果或 AI 摘要机会，指导页面结构和富媒体优化。
分析历史自然结果的流量价值与页面权重，筛选高潜力和高价值竞争页面，建立 SEO 优级模型。
结合搜索意图与历史 SERP制定选题策略，区分信息型、商业型和交易型需求，提高与用户搜索阶段的匹度。

Google 历史数据库完整数据 ​

认证 ​

请求地址 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

计费 ​

地区和语言代码 ​

数据结构概览 ​

历史数据 ​

历史 SERP 数据 ​

keyword_difficulty ​

item_types ​

SERP 通用字段 ​

自然结果 organic ​

rating ​

price ​

about_this_result ​

rank_info ​

付费结果 paid ​

常见 SERP 特征字段 ​

featured_snippet ​

answer_box ​

people_also_ask ​

knowledge_graph ​

carousel 与 multi_carousel ​

images ​

shopping 与 popular_products ​

local_pack 与 local_services ​

top_stories ​

Google 历史数据库完整数据

认证

请求地址

请求示例

cURL

Python

TypeScript

计费

地区和语言代码

数据结构概览

历史数据

历史 SERP 数据

`keyword_difficulty`

`item_types`

SERP 通用字段

自然结果 `organic`

`rating`

`price`

`about_this_result`

`rank_info`

付费结果 `paid`

常见 SERP 特征字段

`featured_snippet`

`answer_box`

`people_also_ask`

`knowledge_graph`

`carousel` 与 `multi_carousel`

`images`

`shopping` 与 `popular_products`

`local_pack` 与 `local_services`

`top_stories`