Google 历史搜索量查询

接口说明

该接口用于实时查询 Google 的历史搜索量数据，并返回以下信息：

历史搜索量
当前平均点击成本（CPC）
付费搜索竞争度
SERP 信息
可选的点击流归因指标
属性、难度与外链均值数据

历史搜索量最早可追溯至 2019 年初，获取结果基于「 + 地域 + 语言」组合返回。

数据源： 本平台数据库底层数据基于 Google Ads API。指标通常按月更新；如果平台数据源对某个月的搜索量进行了回写修正，本接口也会同步更新对应数值。

请求方式

POST https://api.seermartech.cn/v3/dataforseo_labs/google/historical_search_volume/live

计费说明

该接口按请求计费。是否扣费、金额以及最终价格，请以响应中的 cost 字段为准。

启用 include_clickstream_data=true 后，请求价格会变为双倍。

调用限制

每分钟最多可发起 2000 次 API 调用
最多支持 30 个并发请求
POST 请求体为 UTF-8 编码的 JSON
请求体格式为 JSON 数组：[{ ... }]

支持的地域与语言

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

/v3/dataforseo_labs/locations_and_languages

请求参数

字段	类型	说明
`keywords`	array	填。数组。最多 `700` 个；每个最长 `80` 个字符；每个短语最多 `10` 个单词。系统会自动转为小写。返回结果中每个会单独输出。如果某些未出现在结果中，表示数据库中不存在该数据；这类未返回的不会计费。
`location_name`	string	地域名。未传 `location_code` 时填。`location_name` 与 `location_code` 二选一。示例：`United Kingdom`
`location_code`	integer	地域编码。未传 `location_name` 时填。`location_name` 与 `location_code` 二选一。示例：`2840`
`language_name`	string	语言名。未传 `language_code` 时填。`language_name` 与 `language_code` 二选一。示例：`English`
`language_code`	string	语言编码。未传 `language_name` 时填。`language_name` 与 `language_code` 二选一。示例：`en`
`include_serp_info`	boolean	是否在结果中每个对应的 SERP 信息。设为 `true` 时，会返回 `serp_info` 对象，搜索结果数量、 URL、SERP 特征等。默认值：`false`
`include_clickstream_data`	boolean	是否返回基于点击流的扩展指标。设为 `true` 时，响应中会 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream`、`keyword_info_normalized_with_bing`。默认值：`false`。开启后价格翻倍。
`tag`	string	自定义任务标识，可用于请求与结果匹。最长 `255` 字符。响应中的 `data` 对象会原样返回该值。

响应结构

接口返回 JSON，对象中 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码，完整列表见 `/v3/appendix/errors`
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用
`tasks_count`	integer	`tasks` 数组中的任务数
`tasks_error`	integer	返回错误的任务数
`tasks`	array	任务结果数组

`tasks[]` 字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	该任务费用
`result_count`	integer	`result` 数组数
`path`	array	请求路径
`data`	object	原样返回请求参数
`result`	array	获取结果

`result[]` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型
`location_code`	integer	请求中的地域编码
`language_code`	string	请求中的语言编码
`items_count`	integer	`items` 数组中的结果数
`items`	array	结果列表

`items[]` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型
`keyword`	string	。返回时会对 `%##` 做解码，`+` 会被解码为空格
`location_code`	integer	请求中的地域编码；无数据时为 `null`
`language_code`	string	请求中的语言编码
`search_partners`	boolean	是否 Google 合作搜索网络数据。`true` 表示 Google 及合作伙伴站点；`false` 表示 Google 搜索站点
`keyword_info`	object	基础指标
`clickstream_keyword_info`	object / null	点击流数据，需 `include_clickstream_data=true`
`keyword_properties`	object	属性
`serp_info`	object / null	SERP 数据；未开启 `include_serp_info` 或无数据时为 `null`
`avg_backlinks_info`	object	对应前 10 自然结果的平均外链数据
`keyword_info_normalized_with_bing`	object	使用 Bing 搜索量归一化后的搜索量数据
`keyword_info_normalized_with_clickstream`	object	使用点击流数据归一化后的搜索量数据

字段详解

`keyword_info`

字段	类型	说明
`se_type`	string	搜索引擎类型
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`competition`	float	竞争度，范围 `0` 到 `1`，基于 Google Ads 数据
`competition_level`	string	付费搜索竞争等级，可选：`LOW`、`MEDIUM`、`HIGH`；未知时为 `null`
`cpc`	float	历史平均点击成本，单位为平台币种 USD
`search_volume`	integer	平均月搜索量
`low_top_of_page_bid`	float	首页顶部广告位较低出价参考值
`high_top_of_page_bid`	float	首页顶部广告位较高出价参考值
`categories`	array	产品/服务分类列表
`monthly_searches`	array	月度搜索量明细
`search_volume_trend`	object	搜索量趋势变化

`monthly_searches[]`

字段	类型	说明
`year`	integer	年
`month`	integer	月
`search_volume`	integer	该月搜索量

`search_volume_trend`

字段	类型	说明
`monthly`	integer	相比上月的搜索量变化百分比
`quarterly`	integer	相比上季度的搜索量变化百分比
`yearly`	integer	相比上年的搜索量变化百分比

`clickstream_keyword_info`

在 include_clickstream_data=true 时返回。

字段	类型	说明
`search_volume`	integer	基于点击流计算的平均月搜索量
`last_updated_time`	string	点击流数据更新时间，UTC 格式
`gender_distribution`	object	按性别划分的点击流分布
`age_distribution`	object	按年龄划分的点击流分布
`monthly_searches`	array	月度点击流搜索量

`gender_distribution`

字段	类型	说明
`female`	integer	点击流数据中的女性用户数
`male`	integer	点击流数据中的男性用户数

`age_distribution`

字段	类型	说明
`18-24`	integer	18-24 岁用户数
`25-34`	integer	25-34 岁用户数
`35-44`	integer	35-44 岁用户数
`45-54`	integer	45-54 岁用户数
`55-64`	integer	55-64 岁用户数

`keyword_properties`

字段	类型	说明
`se_type`	string	搜索引擎类型
`core_keyword`	string	分组中的核心词；若无法识别同义词分组则为 `null`
`synonym_clustering_algorithm`	string	同义词识别算法。可选：`keyword_metrics`、`text_processing`；无法识别时为 `null`
`keyword_difficulty`	integer	自然搜索前 10 排名难度，范围 `0-100`
`detected_language`	string	系统识别出的语言
`is_another_language`	boolean	语言是否与请求语言不一致

`serp_info`

若 include_serp_info=false 或数据库无该 SERP 数据，则为 null。

字段	类型	说明
`se_type`	string	搜索引擎类型
`check_url`	string	直达搜索结果页的校验 URL
`serp_item_types`	array	SERP 中出现的结果类型
`se_results_count`	string	搜索结果总数
`last_updated_time`	string	最近一次 SERP 数据更新时间
`previous_updated_time`	string	上一次 SERP 数据更新时间

serp_item_types 可能的类型：

answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_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, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview

注意：返回明细结果适用于 organic、paid、featured_snippet、local_pack 。

`avg_backlinks_info`

该对象表示对应 Google 自然结果前 10 名页面的平均外链表现。

字段	类型	说明
`se_type`	string	搜索引擎类型
`backlinks`	float	平均外链数
`dofollow`	float	平均 dofollow 外链数
`referring_pages`	float	平均引用页面数
`referring_domains`	float	平均引用域名数
`referring_main_domains`	float	平均主域名数
`rank`	float	平均 rank 值
`main_domain_rank`	float	平均主域 rank 值
`last_updated_time`	string	外链数据更新时间

`keyword_info_normalized_with_bing`

字段	类型	说明
`last_updated_time`	string	数据集更新时间
`search_volume`	integer	当前搜索量
`is_normalized`	boolean	是否已基于 Bing 数据归一化
`monthly_searches`	array	月度搜索量

`keyword_info_normalized_with_clickstream`

字段	类型	说明
`last_updated_time`	string	数据集更新时间
`search_volume`	integer	当前搜索量
`is_normalized`	boolean	是否已基于点击流数据归一化
`monthly_searches`	array	月度搜索量

上述两个对象中的 monthly_searches[] 结构一致：

字段	类型	说明
`year`	integer	年
`month`	integer	月
`search_volume`	integer	当月搜索量

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_search_volume/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keywords": ["phone", "watch"],
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_search_volume/live"
payload = [
 {
 "keywords": ["phone", "watch"],
 "location_name": "United States",
 "language_name": "English",
 "include_serp_info": True
 }
]
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 postArray = [
 {
 keywords: ["phone", "watch"],
 language_name: "English",
 location_code: 2840,
 include_serp_info: true
 }
];

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

响应示例

json

{
 "version": "0.1.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1100 sec.",
 "cost": 0.0102,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "historical_search_volume",
 "se_type": "google",
 "language_name": "English",
 "location_code": 2840,
 "keywords": ["phone", "watch"],
 "include_serp_info": true
 },
 "result": [
 {
 "items": [
 {
 "se_type": "google",
 "keyword": "phone",
 "location_code": 2840,
 "language_code": "en",
 "search_partners": false,
 "keyword_info": {
 "search_volume_trend": {
 "monthly": 22,
 "quarterly": 22,
 "yearly": 0
 }
 },
 "clickstream_keyword_info": null,
 "keyword_properties": {
 "se_type": "google",
 "core_keyword": null,
 "synonym_clustering_algorithm": "text_processing",
 "keyword_difficulty": 83,
 "detected_language": "en",
 "is_another_language": false
 },
 "serp_info": {
 "se_type": "google",
 "check_url": "https://www.google.com/search?q=phone&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&glp=1&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": ["organic", "paid"],
 "se_results_count": 19880000000,
 "last_updated_time": "2024-07-15 00:43:34 +00:00",
 "previous_updated_time": "2024-05-18 22:29:28 +00:00"
 },
 "avg_backlinks_info": {
 "se_type": "google",
 "backlinks": 6835.7,
 "dofollow": 3775.6,
 "referring_pages": 5352.2,
 "referring_domains": 1100.3,
 "referring_main_domains": 955.1,
 "rank": 369.3,
 "main_domain_rank": 681.2,
 "last_updated_time": "2024-07-14 21:43:39 +00:00"
 },
 "keyword_info_normalized_with_bing": {
 "last_updated_time": "2024-08-17 01:41:37 +00:00",
 "search_volume": 324416,
 "is_normalized": true,
 "monthly_searches": []
 },
 "keyword_info_normalized_with_clickstream": {
 "last_updated_time": "2024-08-11 13:24:34 +00:00",
 "search_volume": 368000,
 "is_normalized": true,
 "monthly_searches": []
 }
 },
 {
 "se_type": "google",
 "keyword": "watch",
 "location_code": 2840,
 "language_code": "en",
 "search_partners": false,
 "keyword_info": {
 "se_type": "google",
 "last_updated_time": "2024-08-12 21:33:32 +00:00",
 "competition": 0.97,
 "competition_level": "HIGH",
 "cpc": 1.36,
 "search_volume": 450000,
 "low_top_of_page_bid": 0.55,
 "high_top_of_page_bid": 3.25,
 "categories": [],
 "monthly_searches": [],
 "search_volume_trend": {
 "monthly": 22,
 "quarterly": 22,
 "yearly": 0
 }
 },
 "clickstream_keyword_info": null,
 "keyword_properties": {
 "se_type": "google",
 "core_keyword": "watches",
 "synonym_clustering_algorithm": "text_processing",
 "keyword_difficulty": 37,
 "detected_language": "en",
 "is_another_language": false
 },
 "serp_info": {
 "se_type": "google",
 "check_url": "https://www.google.com/search?q=watch&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&glp=1&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": ["organic", "paid"],
 "se_results_count": 18430000000,
 "last_updated_time": "2024-07-15 00:43:26 +00:00",
 "previous_updated_time": "2024-05-18 22:29:29 +00:00"
 },
 "avg_backlinks_info": {
 "se_type": "google",
 "backlinks": 298278.4,
 "dofollow": 293580.4,
 "referring_pages": 295932.3,
 "referring_domains": 961.9,
 "referring_main_domains": 812.7,
 "rank": 272.8,
 "main_domain_rank": 520.9,
 "last_updated_time": "2024-07-14 21:43:28 +00:00"
 },
 "keyword_info_normalized_with_bing": {
 "last_updated_time": "2024-08-17 05:40:22 +00:00",
 "search_volume": 253808,
 "is_normalized": true,
 "monthly_searches": []
 },
 "keyword_info_normalized_with_clickstream": {
 "last_updated_time": "2024-08-12 21:33:32 +00:00",
 "search_volume": 450000,
 "is_normalized": true,
 "monthly_searches": []
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code 表示整次请求的处理状态
tasks[].status_code 表示单个任务的处理状态
完整错误码与说明请参考：/v3/appendix/errors

建议在接时至少处理以下：

鉴权失败
参数缺失或格式错误
地域/语言不支持
请求频率限
单个无数据库结果
任务级成功但部分未返回

使用建议

批量查询时，优检查返回的 items_count 是否与请求数量一致。
如需分析 SERP 版位环境，开启 include_serp_info=true。
如需更细的人群维度或归一化搜索量，开启 include_clickstream_data=true，但应注意价格翻倍。
若要建立时间序列分析模型，建议重点使用 monthly_searches 和 search_volume_trend。
对于未出现在结果中的，可视为当前数据库暂无覆盖，无需重试计费确认。

实用场景

评估季节性：拉取过去多个月的 monthly_searches，识别旺季与淡季，为排期和广告预算分提供依据。
筛选高价值投放词：结合 search_volume、cpc、competition，找到“搜索量高且竞争适中”的，提高投放效率。
判断自然排名难度：使用 keyword_difficulty 和 avg_backlinks_info 评估前 10 的难度， SEO 选题与资源决策。
识别 SERP 结果形态：通过 serp_item_types 判断是否触发精选摘要、本地、图片等模块，优化结构与页面类型。
分析跨语言或跨地区差异：按不同 location_code、language_code 批量查询同一组词，对比需求规模变化，支持化 SEO 与本地化投放。

Google 历史搜索量查询 ​

接口说明 ​

请求方式 ​

计费说明 ​

调用限制 ​

支持的地域与语言 ​

请求参数 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段 ​

字段详解 ​

keyword_info ​

monthly_searches[] ​

search_volume_trend ​

clickstream_keyword_info ​

gender_distribution ​

age_distribution ​

keyword_properties ​

serp_info ​

avg_backlinks_info ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​