SeerMarTech API 文档

主题

Google 历史量数据库 ​

概述 ​

Google 历史量数据库是一个统一数据集，整合了以下两类历史数据：

  • 历史 Google SERP 数据库：数百万份按月归档的 Google 搜索结果页快，采用 JSON 结构保存，并覆盖丰富的 SERP 特性，例如精选摘要、知识图谱、People Also Ask、Top Stories 等。
  • 历史 Google 数据库：数十亿，并附带历史指标，例如搜索量、竞争度等。

使用说明：

  • 历史数据：自 2021-09-01 起可用
  • 历史 SERP 数据：可查询过去 365 天
  • 数据格式：提供 JSON

如需查询支持的地域与语言代码，可调用：

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

计费说明 ​

该数据库的费用取决于数据库规模及地域参数。

  • 原文未提供固定单价，无法直接换算为人民币参考价
  • 扣费以响应头 X-SeerMarTech-Charge-CNY 为准

数据结构说明 ​

顶层字段 ​

字段名类型说明
keywordstring，UTF-8 编码
locationinteger地域代码，对应唯一地域标识，例如 2840 表示美国
languagestring语言代码，例如 en 表示英语
spellstring搜索引擎自动纠错后的
spell_typestring自动纠错类型，可选值：did_you_mean、showing_results_for、no_results_found_for、including_results_for
keyword_info_historyobject返回的历史数据
serp_info_historyobject返回可用的历史 SERP 数据
extraobject附加信息
search_intent_infoobject搜索意图信息

keyword_info_history 字段说明 ​

该对象按月份组织，月份键名为 YYYYMM 格式，例如 202109。

月度指标字段 ​

字段名类型说明
$dateobject月份变量，格式为 YYYYMM
search_volumeinteger平均月搜索量
cpcfloat历史平均点击成本（USD）。该值基于 Google Ads 提供的 high_top_of_page_bid 推算
competitionfloat竞争度，范围 0 到 1
competition_levelstring付费搜索竞争等级，可选值：LOW、MEDIUM、HIGH；未知时为 null
low_top_of_page_bidfloat广告出现在首页顶部的较低出价参考值
high_top_of_page_bidfloat广告出现在首页顶部的较高出价参考值
time_updatestring数据最近更新时间，ISO 8601 格式
categoriesarray产品或服务分类
historyobject过去 4 年该在指定地域的月度搜索量，例如 "202109": 40

serp_info_history 字段说明 ​

该对象按月份返回 SERP 历史信息，每个月份对应一个独立对象。

月度 SERP 概览字段 ​

字段名类型说明
check_urlstring搜索结果直达链接，可用于核验结果
items_countintegerserp 数组中的结果数量
keyword_difficultyinteger难度，范围 0 到 100，表示自然搜索前 10 的难度
se_results_countintegerSERP 总结果数
time_updatestring当前 SERP 数据更新时间，ISO 8601 格式
previous_updated_timestring上一个版本的 SERP 更新时间，ISO 8601 格式
item_typesarraySERP 中出现的结果类型列表
serparray该次快中抓取到的 SERP素列表

item_types 可选值 ​

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 的对象字段会有所不同。

通用字段 ​

字段名类型说明
typestringSERP素类型
positionstring素在页面中的对齐位置，可选 left、right
xpathstring素在页面中的 XPath
rank_groupinteger同类型组排名
rank_absoluteinteger在整个 SERP 中的绝对排名
etvfloat预估自然流量
traffic_costfloat将自然流量换算为付费流量的预估成本，或月度搜索流量预估成本

主要 SERP素字段 ​

1）organic 自然结果 ​

字段名类型说明
titlestring标题
pre_snippetstring描述前附加信息
descriptionstring描述文本
breadcrumbstring面屑
imagesarray图片列表
is_imageboolean是否含图片
is_videoboolean是否含视频
is_featured_snippetboolean是否为精选摘要来源
extended_snippetstring描述后附加信息
amp_versionboolean是否有 AMP 版本
ratingobject评分信息
highlightedarray描述中加粗高亮词
linksarray站点链接
domainstring域名
main_domainstring主域名，不含子域名
urlstring绝对 URL
relative_urlstring相对 URL
is_maliciousboolean是否被标记为恶意
faqobjectFAQ 扩展块
is_newboolean相比上一版是否为新结果
is_upboolean相比上一版排名是否上升
is_downboolean相比上一版排名是否下降
previous_rank_absoluteinteger上一版绝对排名
extended_people_also_searcharray返回搜索结果后展示的搜索扩展
cache_urlstring页面缓存链接
priceobject商品/服务价格信息
related_search_urlstring相似搜索 URL
related_resultarray同域名结果
about_this_resultobject“此结果”信息
is_web_storyboolean是否为 Web Story
timestampstring结果发布时间
rank_infoobject页面与主域权重信息

rating 结构 ​

字段名类型说明
rating_typestring评分类型：Max5、Percents、CustomMax
valueinteger/float评分值
votes_countinteger评价数
rating_maxinteger评分上限

rank_info 结构 ​

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

about_this_result 结构 ​

字段名类型说明
typestring固定为 about_this_result_element
urlstring结果 URL
sourcestring附加信息来源
source_infostring来源说明或站点背景信息
source_urlstring来源页 URL
languagestring结果语言
locationstring结果适用地域
search_termsarray匹到的搜索词
related_termsarray搜索词

2）paid 付费结果 ​

字段名类型说明
titlestring广告标题
domainstring广告显示域名
descriptionstring广告描述
breadcrumbstring广告面屑
urlstring广告绝对 URL
main_domainstring主域名
relative_urlstring相对链接
highlightedarray加粗高亮词
extraobject额外信息，如 ad_aclk
description_rowsarray扩展描述
linksarray广告附加链接
is_newboolean是否为新广告结果
is_upboolean排名是否上升
is_downboolean排名是否下降
previous_rank_absoluteinteger上一版绝对排名
priceobject价格信息
rank_infoobject权重信息

3）featured_snippet 精选摘要 ​

字段名类型说明
titlestring摘要标题
featured_titlestring摘要来源页标题
descriptionstring摘要描述
tableobject表格型摘要
domainstring域名
main_domainstring主域名
urlstring结果 URL
relative_urlstring相对 URL
is_newboolean是否为新增结果
is_upboolean是否排名上升
is_downboolean是否排名下降
previous_rank_absoluteinteger上一版绝对排名
imagesarray图片信息
timestampstring发布时间
rank_infoobject权重信息

4）people_also_ask 人还问 ​

字段名类型说明
itemsarray问题列表
typestring固定为 people_also_ask

people_also_ask_element ​

字段名类型说明
titlestring问题标题
seed_questionstring触发后续展开的问题
xpathstring问题 XPath
expanded_elementarray展开后的答案

展开中可能：

  • people_also_ask_expanded_element
  • people_also_ask_ai_overview_expanded_element
  • ai_overview_video_element
  • ai_overview_table_element
  • ai_overview_expanded_element

这些对象可能返回标题、正文、Markdown、表格、图片、链接、引用来源、异步加载标记等字段。

5）knowledge_graph 知识图谱 ​

知识图谱对象可能以下字段：

字段名类型说明
titlestring标题
subtitlestring副标题
descriptionstring描述
card_idstring卡片 ID
urlstring链接
logo_urlstringLogo 图片地址
itemsarray知识图谱组件

常见组件类型：

  • knowledge_graph_carousel_item
  • knowledge_graph_description_item
  • knowledge_graph_images_item
  • knowledge_graph_ai_overview_item
  • knowledge_graph_list_item
  • knowledge_graph_row_item
  • knowledge_graph_part_item
  • knowledge_graph_shopping_item
  • knowledge_graph_expanded_item

这些组件可返回链接、图片、列表、表格、商品价格、AI 概览引用等丰富字段。

6）常见 SERP素类型 ​

以下类型也可能出现在 serp 中，通常 title、items、url、position、xpath、rank_group、rank_absolute、etv、traffic_cost 等字段：

  • carousel
  • multi_carousel
  • answer_box
  • related_searches
  • people_also_search
  • local_pack
  • top_stories
  • twitter
  • map
  • google_flights
  • google_reviews
  • video
  • images
  • shopping
  • jobs
  • events
  • mention_carousel
  • find_results_on
  • stocks_box
  • currency_box
  • recipes
  • top_sights
  • scholarly_articles
  • popular_products
  • podcasts
  • questions_and_answers
  • hotels_pack
  • google_posts
  • visual_stories
  • commercial_units
  • local_services
  • google_hotels
  • math_solver
  • product_considerations
  • short_videos
  • refine_products
  • explore_brands
  • perspectives
  • discussions_and_forums
  • compare_sites
  • third_party_reviews
  • ai_overview

extra 字段说明 ​

字段名类型说明
core_keywordstring聚类中的核心；若无匹则为 null
synonym_clustering_algorithmstring同义词识别算法，可选值：keyword_metrics、text_processing
detected_languagestring系统识别出的语言
keyword_difficultyinteger难度，范围 0 到 100

search_intent_info 字段说明 ​

字段名类型说明
main_intentstring主要搜索意图，可选值：informational、navigational、commercial、transactional
foreign_intentarray补搜索意图，取值同上
last_updated_timestring搜索意图数据最近更新时间，ISO 8601 格式

获取地域与语言代码 ​

可通过以下接口获取可用的地域与语言：

bash
curl -X GET "https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages" \
 -H "Authorization: Bearer smt_live_YOUR_KEY"

Python 示例 ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY"
}

resp = requests.get(url, headers=headers, timeout=30)
print(resp.json)

TypeScript 示例 ​

typescript
const resp = await fetch("https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages", {
 method: "GET",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY"
 }
});

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

JSON 数据示例 ​

以下为数据库中单条记录的示意结构。原始示例较长，下面保留核心层级，便于理解字段组织方式：

json
{
 "keyword": "coleman xtreme 5 cooler",
 "location": 2840,
 "language": "en",
 "spell": null,
 "spell_type": null,
 "keyword_info_history": {
 "202108": {
 "search_volume": 1600,
 "cpc": 0.438697,
 "competition": 1,
 "competition_level": null,
 "low_top_of_page_bid": null,
 "high_top_of_page_bid": null,
 "time_update": "2021-09-15T15:47:29.4648874Z",
 "categories": [],
 "history": {
 "202009": 1600,
 "202010": 1000,
 "202011": 720
 }
 }
 },
 "serp_info_history": [
 {
 "check_url": "https://www.google.com/search?q=coleman%20xtreme%205%20cooler&num=100&hl=en&gl=US",
 "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",
 "featured_snippet",
 "people_also_ask",
 "images",
 "shopping"
 ],
 "serp": [
 {
 "type": "organic",
 "title": "70 Quart Xtreme® 5 Cooler | Coleman",
 "description": "Food and drinks—and the fun—last longer...",
 "domain": "www.coleman.com",
 "main_domain": "coleman.com",
 "url": "https://www.coleman.com/coolers/hard-coolers/70-quart-xtreme-5-cooler/SAP_3000001836.html",
 "is_new": false,
 "is_up": false,
 "is_down": false,
 "rank_absolute": 2,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/div",
 "traffic_cost": 213.3822208,
 "rank_group": 1,
 "etv": 486.4
 },
 {
 "type": "people_also_ask",
 "items": [
 {
 "type": "people_also_ask_element",
 "title": "How many quarts is the Coleman Xtreme 5 cooler?"
 }
 ],
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/div/div/div/div",
 "rank_group": 1,
 "rank_absolute": 4,
 "etv": 486.4,
 "traffic_cost": 213.3822208
 }
 ]
 }
 ],
 "extra": {
 "core_keyword": null,
 "detected_language": "en",
 "keyword_difficulty": 23
 },
 "search_intent_info": {
 "main_intent": "commercial",
 "foreign_intent": [],
 "last_updated_time": "2023-03-04T13:56:18.6047890Z"
 }
}

注意事项 ​

  1. 本数据库是离线历史数据库，不是实时抓取接口。
  2. 历史 SERP 数据与历史数据的可用时间范围不同：
  • 历史：自 2021-09-01
  • SERP 历史：最近 365 天
  1. 返回结构非常大， serp 中不同 type 的字段差异显著，建议按 type 做分支解析。
  2. cpc、competition、keyword_difficulty、etv、traffic_cost 等字段均为估算或建模结果，应结合业务场景解读。
  3. 某些字段在特定结果类型中可能为 null，属于正常。

实用场景 ​

  • 回溯趋势：查看某近几年搜索量、CPC、竞争度变化，选词、季节性判断和预算规划。
  • 分析 SERP 结构演变：比较不同月份同一的 SERP 特性占比变化，识别精选摘要、PAA、AI Overview 等新模块对自然点击的影响。
  • 监控排名波动与新结果出现：利用 is_new、is_up、is_down、previous_rank_absolute 字段，追踪历史排名变化和竞品替换。
  • 识别搜索意图变化：结合 search_intent_info 与历史 SERP 结果，判断是否从信息型逐步转向商业型或交易型。
  • 构建 SEO 研究样本库：批量沉淀历史与 SERP 快，为行业分析、策略验证、模型训练和归因研究提供基础数据。

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

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