Google 历史数据（实时）

接口说明

该接口用于查询指定在 Google 维度下的历史数据：

• 搜索量
• 平均点击单价（CPC）
• 付费搜索竞争度
• 月度搜索量
• 搜索量趋势变化

可返回自 2021 年 8 月 起的历史数据，可用范围取决于、地区与语言组合。

数据源： 本平台数据库 数据基础： 基于 Google Ads API 更新频率： 指标通常在平台数据源完成月度更新后，每月同步一次。部分月份 Google 可能会回写历史搜索量，本接口也会据此更新历史值。

请求地址

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

计费与频率限制

• 本接口按请求计费
• 扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 参考价约 ¥0.1616 / 次

频率限制：

• 每分钟最多 2000 次 API 调用
• 最多 30 个并发请求

请求体格式

所有 POST 数据均使用 UTF-8 编码的 JSON 格式提交。 请求体为 JSON 数组：

[
 {
 "keywords": ["iphone"],
 "location_code": 2840,
 "language_name": "English"
 }
]

请求参数

字段名	类型	说明
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
tag	string	可选。用户自定义任务标识，最长 255 字符。可用于请求与响应匹，返回时会出现在响应的 data 对象中。

地区与语言列表

可通过以下容路径查询支持的地区和语言：

/v3/dataforseo_labs/locations_and_languages

响应结构

接口返回 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[] 字段

字段名	类型	说明
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	请求中的语言编码
history	array	该的历史数据数组

history[] 字段

字段名	类型	说明
year	integer	年份
month	integer	月份
keyword_info	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	平均月搜索量，表示该在 google.com 上的大致搜索次数
low_top_of_page_bid	float	首页顶部广告展示的较低出价参考值；大致高于最低出价样本中的 20%
high_top_of_page_bid	float	首页顶部广告展示的较高出价参考值；大致高于最低出价样本中的 80%
categories	array	产品与服务分类列表
monthly_searches	array	最近 12 个月的月度搜索量明细
search_volume_trend	object	搜索量趋势变化，按百分比表示相较于上一周期的变化

monthly_searches[] 字段

字段名	类型	说明
year	integer	年份
month	integer	月份
search_volume	integer	该月平均搜索量

search_volume_trend 字段

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

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_keyword_data/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keywords": ["iphone", "iphone 15", "apple phone"],
 "language_name": "English",
 "location_code": 2840,
 "tag": "historical-keyword-demo"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_keyword_data/live"
payload = [
 {
 "keywords": ["iphone", "iphone 15", "apple phone"],
 "location_name": "United States",
 "language_name": "English",
 "tag": "historical-keyword-demo"
 }
]
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 postArray = [
 {
 keywords: ["iphone", "iphone 15", "apple phone"],
 language_name: "English",
 location_code: 2840,
 tag: "historical-keyword-demo"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_keyword_data/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);
 });

响应示例

{
 "version": "0.1.20241227",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1578 sec.",
 "cost": 0.0101,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1201 sec.",
 "cost": 0.0101,
 "result_count": 1,
 "path": [
 "v3",
 "dataforseo_labs",
 "google",
 "historical_keyword_data",
 "live"
 ],
 "data": {
 "api": "dataforseo_labs",
 "function": "historical_keyword_data",
 "se_type": "google",
 "language_code": "en",
 "location_code": 2840,
 "keywords": ["iphone"]
 },
 "result": [
 {
 "se_type": "google",
 "location_code": 2840,
 "language_code": "en",
 "items_count": 1,
 "items": [
 {
 "se_type": "google",
 "keyword": "iphone",
 "location_code": 2840,
 "language_code": "en",
 "history": [
 {
 "year": 2025,
 "month": 1,
 "keyword_info": {
 "se_type": "google",
 "last_updated_time": "2025-02-06 05:57:16 +00:00",
 "competition": 1,
 "competition_level": "HIGH",
 "cpc": 5.72,
 "search_volume": 1220000,
 "low_top_of_page_bid": 2.66,
 "high_top_of_page_bid": 4.49,
 "categories": [],
 "monthly_searches": [],
 "search_volume_trend": {
 "monthly": -19,
 "quarterly": 0,
 "yearly": 22
 }
 }
 },
 {
 "year": 2024,
 "month": 12,
 "keyword_info": {
 "se_type": "google",
 "last_updated_time": "2025-01-14 06:26:52 +00:00",
 "competition": 1,
 "competition_level": "HIGH",
 "cpc": 7.71,
 "search_volume": 1220000,
 "low_top_of_page_bid": 2.66,
 "high_top_of_page_bid": 6.65,
 "categories": [],
 "monthly_searches": [],
 "search_volume_trend": {
 "monthly": 23,
 "quarterly": 23,
 "yearly": 23
 }
 }
 },
 {
 "year": 2021,
 "month": 8,
 "keyword_info": {
 "se_type": "google",
 "last_updated_time": "2021-09-22 17:41:11 +00:00",
 "competition": 0.9999979568361199,
 "competition_level": null,
 "cpc": 2.501309,
 "search_volume": 1220000,
 "low_top_of_page_bid": null,
 "high_top_of_page_bid": null,
 "categories": [],
 "monthly_searches": [],
 "search_volume_trend": {
 "monthly": 0,
 "quarterly": 22,
 "yearly": null
 }
 }
 }
 ]
 }
 ]
 }
 ]
 }
 ]
}

响应说明

• history 按月返回历史指标，可用于构建长期趋势曲线。
• search_volume_trend.monthly、quarterly、yearly 分别表示相较于上月、上季度、上年的搜索量变化百分比。
• competition_level、low_top_of_page_bid、high_top_of_page_bid 在部分历史月份可能为空，这是平台数据源在对应月份未提供完整广告竞价指标导致的正常。
• 如果请求中的某些未出现在 items 中，表示数据库暂无这些的历史数据；这部分不会计费。

错误处理

建议同时处理两层状态：

1. 顶层状态：检查 status_code
2. 任务层状态：检查 tasks[].status_code

常见成功状态：

• 20000：成功

错误码完整列表请参考容路径：

• /v3/appendix/errors

建议在接时重点处理以下：

• 请求参数缺失或格式错误
• location_name/location_code 未提供
• language_name/language_code 未提供
• keywords过数量或长度限制
• 频率限
• 部分任务成功、部分任务失败

使用建议

• 优使用 location_code 和 language_code，便于系统化处理并减少名称歧义。
• 单次可提交较多，但为了便于错误排查与结果管理，建议按主题或业务线分批请求。
• 若要分析季度性、年度性波动，可直接使用 history 结合 search_volume_trend 构建趋势分析逻辑。
• 如果要做广告投放评估，可结合 cpc、competition、low_top_of_page_bid、high_top_of_page_bid 综合判断商业价值。

实用场景

• 分析季节性波动：查看某类产品词在不同月份的搜索量变化，帮助制定发布时间表和营销节点计划。
• 评估投放商业价值：结合 cpc、竞争度与顶部出价区间，筛选高转化潜力词，优化广告预算分。
• 追踪核心词长期趋势：持续监控品牌词、品类词、自有产品词的多年历史表现，识别增长、衰退或异常波动。
• 比较不同地区搜索需求：对同一批在不同 location_code 下分别查询，判断市场需求差异，支持化 SEO 与本地化投放。
• 构建机会评分模型：将搜索量、趋势、竞争度和 CPC 组合成评分体系，选题、投放和落地页优级排序。