SeerMarTech API 文档

主题

历史搜索量（旧版）实时查询 ​

接口说明 ​

该接口用于获取的历史搜索量及广告投放指标，支持 Google 与 Bing 数据源。返回：

  • 历史搜索量
  • 当前 CPC（单次点击费用）
  • 付费搜索竞争度
  • 当前展示量（impressions）
  • SERP 信息（可选）

历史搜索量最早可追溯至 2019 年初，并且需要结合、地区和语言进行查询。

说明：这是 旧版（Legacy） 接口结构。虽然平台 API 已在 2022-03-19 更新了请求与响应结构，但该旧版接口仍保持容支持。 如需新版结构，可参考对应新版文档。

数据源： 本平台数据库 底层数据基于 Google Ads API 与 Bing Ads API。指标通常在平台数据源完成月度更新后同步更新。某些，平台数据源会回溯修正某个月份的搜索量值，本接口也会同步更新。

请求信息 ​

请求方式： POST请求地址：

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

请求体格式：

json
[
 {
 "keywords": ["phone", "watch"],
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true
 }
]
  • POST 数据为 UTF-8 编码的 JSON
  • 请求体是 JSON 数组 [{ ... }]
  • 每分钟最多可发送 2000 次 API 调用

计费说明 ​

该接口按请求计费。原文未提供固定单价，因此无法直接换算为人民币参考价。

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

请求参数 ​

字段名类型说明
keywordsarray填。列表。最多 700 个；每个最多 80 个字符；每个短语最多 10 个词。系统会自动转为小写。返回结果会按单独数组项提供。如果某些未出现在结果中，表示数据库中不存在该数据；未返回的不会计费。
location_namestring地区名。若未传 location_code，则此字段填。location_name 与 location_code 二选一填。示例：United Kingdom
location_codeinteger地区编码。若未传 location_name，则此字段填。location_name 与 location_code 二选一填。示例：2840
language_namestring语言名。若未传 language_code，则此字段填。language_name 与 language_code 二选一填。示例：English
language_codestring语言编码。若未传 language_name，则此字段填。language_name 与 language_code 二选一填。示例：en
include_serp_infoboolean是否为每个返回 SERP 数据。可选。设为 true 时，响应中会 serp_info，搜索结果数量、 URL、SERP 特征等。默认值：false
order_byarray结果排序规则。可选。支持升序 asc、降序 desc。默认按 relevance 排序，以便返回更的结果。relevance 是排序标识，不会出现在 result 数组中。单次请求最多可设置 3 条排序规则。
tagstring用户自定义任务标识。可选，最大长度 255。可用于将请求与结果进行匹；响应中会在 data 对象中原样返回。

地区和语言 ​

可通过以下容路径获取支持的地区与语言列表：

  • /v3/dataforseo_labs/locations_and_languages

响应结构 ​

接口返回 JSON，顶层 tasks 数组。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码
status_messagestring通用状态信息
timestring执行耗时，单位秒
costfloat本次所有任务总费用，单位 USD
tasks_countintegertasks 数组中的任务数
tasks_errorinteger返回错误的任务数
tasksarray任务结果数组

建议对 status_code 和任务级别的错误状态建立完整的异常处理机制。 错误码可参考：/v3/appendix/errors

tasks[] 字段 ​

字段名类型说明
idstring任务 ID，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态信息
timestring任务执行耗时
costfloat当前任务费用，单位 USD
result_countintegerresult 数组数量
patharrayURL 路径
dataobject与请求中提交的参数一致
resultarray获取结果数组

result[] 字段 ​

字段名类型说明
location_codeinteger请求中的地区编码
language_codestring请求中的语言编码
items_countintegeritems 数组中的结果数量
itemsarray及数据

items[] 字段 ​

字段名类型说明
keywordstring。返回时会对 %## 进行解码，+ 会被还原为空格。
location_codeinteger请求中的地区编码；若无数据则为 null
keyword_infoobjectGoogle 维度指标
keyword_propertiesobject附加属性
impressions_infoobject展示量数据
bing_keyword_infoobjectBing 维度指标
serp_infoobjectSERP 数据；若未启用 include_serp_info=true 或数据库无 SERP 数据，则为 null

字段详解 ​

keyword_info ​

字段名类型说明
last_updated_timestring数据更新时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
competitionfloat竞争度，基于 Google Ads 数据，范围 0 到 1
cpcfloat历史平均 CPC，单位 USD
search_volumeinteger月均搜索量，表示在 google.com 上的近似月均搜索次数
categoriesarray产品和服务分类
monthly_searchesarray最近 12 个月月度搜索量明细

keyword_info.monthly_searches[] ​

字段名类型说明
yearinteger年份
monthinteger月份
search_volumeinteger该月搜索量

keyword_properties ​

字段名类型说明
core_keywordstring分组主。若为 null，表示数据库中没有满足条件的主。
keyword_difficultyinteger自然排名难度，范围 0-100。表示自然搜索前 10 的难度，基于 SERP 前 10 页面外链画像等因素计算。

impressions_info ​

daily_impressions 指标可作为 Google 搜索量更精细的替代参考。该对象基于 bid=999 的条件返回，用于尽量降低账户个体差异的影响。

字段名类型说明
last_updated_timestring展示量数据更新时间，UTC 格式
bidinteger最大 CPC 出价。该接口固定按 999 的出价场景返回，以获得更高展示量覆盖。
match_typestring匹类型：exact、broad、phrase
ad_position_minfloat广告最低展示位置
ad_position_maxfloat广告最高展示位置
ad_position_averagefloat广告平均展示位置
cpc_minfloat在 bid=999 条件下的最小 CPC（USD）。不代表真实 CPC，真实值请看 keyword_info.cpc
cpc_maxfloat在 bid=999 条件下的最大 CPC（USD）。不代表真实 CPC
cpc_averagefloat在 bid=999 条件下的平均 CPC（USD）。不代表真实 CPC
daily_impressions_minfloat最小日展示量
daily_impressions_maxfloat最大日展示量
daily_impressions_averagefloat平均日展示量
daily_clicks_minfloat最小日点击量
daily_clicks_maxfloat最大日点击量
daily_clicks_averagefloat平均日点击量
daily_cost_minfloat最小日花费，单位 USD
daily_cost_maxfloat最大日花费，单位 USD
daily_cost_averagefloat平均日花费，单位 USD

bing_keyword_info ​

注意：Bing 数据覆盖部分地区和语言组合。

字段名类型说明
last_updated_timestringBing 数据更新时间，UTC 格式
search_volumeintegerBing 上过去一个月的搜索量
monthly_searchesarray按月统计的 Bing 搜索量

bing_keyword_info.monthly_searches[] ​

字段名类型说明
yearinteger年份
monthinteger月份
search_volumeinteger该月搜索量

serp_info ​

如果请求中未设置 include_serp_info=true，或数据库无对应 SERP 数据，则该字段为 null。

字段名类型说明
check_urlstring对应搜索结果页直达链接，可用于校验结果
serp_item_typesarraySERP 中出现的结果类型
se_results_countstring搜索结果总数
last_updated_timestringSERP 数据更新时间，UTC 格式

实可返回完整结果数据的类型主要：organic、paid、featured_snippet、local_pack

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/historical_search_volume/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "language_name": "English",
 "include_serp_info": true,
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ]
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/historical_search_volume/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "location_name": "United States",
 "language_name": "English",
 "include_serp_info": True,
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ]
 }
]

response = requests.post(url, json=data, headers=headers)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const postData = [
 {
 location_name: "United States",
 language_name: "English",
 include_serp_info: true,
 keywords: [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ]
 }
];

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

响应示例 ​

下方示例根据原始文档整理，保留主要字段结构。

json
{
 "version": "0.1.20220131",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1091 sec.",
 "cost": 0.0102,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "historical_search_volume",
 "keywords": ["phone", "watch"],
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true
 },
 "result": [
 {
 "items": [
 {
 "keyword": "phone",
 "keyword_properties": {
 "core_keyword": null,
 "keyword_difficulty": 100
 },
 "impressions_info": {
 "last_updated_time": "2021-12-30 21:53:30 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.12,
 "ad_position_max": 1,
 "ad_position_average": 1.06,
 "cpc_min": 13.11,
 "cpc_max": 16.02,
 "cpc_average": 14.57,
 "daily_impressions_min": 3682.42,
 "daily_impressions_max": 4500.73,
 "daily_impressions_average": 4091.57,
 "daily_clicks_min": 118.16,
 "daily_clicks_max": 144.42,
 "daily_clicks_average": 131.29,
 "daily_cost_min": 1721.19,
 "daily_cost_max": 2103.68,
 "daily_cost_average": 1912.43
 },
 "bing_keyword_info": {
 "last_updated_time": "2021-12-19 12:26:54 +00:00",
 "search_volume": 54530,
 "monthly_searches": []
 },
 "serp_info": {
 "check_url": "https://www.google.com/search?q=phone&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": [],
 "se_results_count": 3430000000,
 "keyword_difficulty": 100,
 "last_updated_time": "2022-01-13 20:59:31 +00:00",
 "previous_updated_time": null
 }
 },
 {
 "keyword": "watch",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "last_updated_time": "2022-01-17 15:57:45 +00:00",
 "competition": 0.9874966013067319,
 "cpc": 3.128769,
 "search_volume": 450000,
 "categories": [],
 "monthly_searches": []
 },
 "keyword_properties": {
 "core_keyword": null,
 "keyword_difficulty": 77
 },
 "impressions_info": {
 "last_updated_time": "2022-01-25 17:41:34 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.19,
 "ad_position_max": 1,
 "ad_position_average": 1.1,
 "cpc_min": 202.56,
 "cpc_max": 247.57,
 "cpc_average": 225.06,
 "daily_impressions_min": 357.55,
 "daily_impressions_max": 437.01,
 "daily_impressions_average": 397.28,
 "daily_clicks_min": 12.86,
 "daily_clicks_max": 15.72,
 "daily_clicks_average": 14.29,
 "daily_cost_min": 2894.66,
 "daily_cost_max": 3537.92,
 "daily_cost_average": 3216.29
 },
 "bing_keyword_info": {
 "last_updated_time": "2021-12-21 12:35:23 +00:00",
 "search_volume": 71910,
 "monthly_searches": []
 },
 "serp_info": {
 "check_url": "https://www.google.com/search?q=watch&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": [],
 "se_results_count": 3430000000,
 "keyword_difficulty": 77,
 "last_updated_time": "2022-01-13 20:57:54 +00:00",
 "previous_updated_time": null
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理 ​

  • 顶层 status_code=20000 表示请求成功
  • 任务级 status_code 用于表示单个任务执行状态
  • 建议同时检查：
  • 顶层 status_code
  • tasks_error
  • 各 tasks[].status_code

错误码说明可参考容路径：

  • /v3/appendix/errors

使用建议 ​

  1. 当你需要同时评估 SEO 搜索需求与广告投放价值时，可联合使用：
  • keyword_info.search_volume
  • keyword_info.cpc
  • keyword_info.competition
  1. 当搜索量不足以反映真实投放潜力时，可重点参考：
  • impressions_info.daily_impressions_average
  1. 若希望结合搜索结果页环境判断自然排名难度，可开启：
  • include_serp_info=true
  1. 对于返回结果中缺失的，不代表请求失败，通常表示数据库中没有该记录，且不会计费。

实用场景 ​

  • 筛选高价值：批量获取的历史搜索量、CPC 与竞争度，快速识别流量潜力和商业价值的词。
  • 分析季节性趋势：利用 monthly_searches 观察过去 12 个月乃至自 2019 年以来的搜索波动，为排期和大促节奏提供依据。
  • 评估自然排名难度：结合 keyword_difficulty 和 serp_info 判断前 10 的难易度，优化 SEO 选词策略。
  • 估算广告潜力：通过 impressions_info 中的日展示、点击和花费区间，预估在广告投放中的可见度和预算需求。
  • 对比 Google 与 Bing 需求差异：同时查看 keyword_info 与 bing_keyword_info，评估不同搜索引擎上的用户需求分布，支持多平台营销布局。

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

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