SeerMarTech API 文档

主题

Google 历史搜索量实时查询 ​

本接口使用 POST /v3/dataforseo_labs/google/historical_search_volume/live，返回 Google 的历史搜索量、当前每次点击费用（CPC）、付费搜索竞争度，以及可选的 SERP 信息。

数据覆盖范围最早可追溯至 2019 年初，取决于、地区和语言组合。数据源基于 Google Ads API，通常在数据源完成月度更新后同步更新。由于 Google 可能重新修订某个月份的搜索量，本接口也会同步更新对应数据。

可通过以下接口查询支持的地区和语言：

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

计费与调用限制 ​

  • 每次请求单独计费。
  • include_clickstream_data 设置为 true 时，请求费用按标准费用的约 2 倍计算。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • 所有 POST 请求体使用 UTF-8 编码的 JSON 格式。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 同时处理的请求数最多为 30 个。
  • keywords 中未返回结果的不会计费。

请求参数 ​

请求体是 JSON 数组，数组中的每个对象代表一个查询任务。

参数类型填说明
keywordsarray是要查询的列表。最多 700 个；每个最多 80 个字符、10 个单词。会被转换为小写，结果中的会单独返回。如果某个未出现在结果中，通常表示数据库中没有对应数据。
location_namestring条件填地区名。未指定 location_code 时填。例如：United Kingdom。
location_codeinteger条件填地区代码。未指定 location_name 时填。例如：2840。
language_namestring条件填语言名。未指定 language_code 时填。例如：English。
language_codestring条件填语言代码。未指定 language_name 时填。例如：en。
include_serp_infoboolean否是否返回每个的 SERP 数据结果数量、查询 URL 和 SERP 特征。默认值为 false。
include_clickstream_databoolean否是否返回基于点击流数据计算的指标。设为 true 后，响应中会 clickstream_keyword_info、keyword_info_normalized_with_clickstream 和 keyword_info_normalized_with_bing。默认值为 false。
tagstring否用户自定义任务标识，最多 255 个字符。该值会原样返回在响应任务的 data 对象中，可用于请求和结果。

> location_name 与 location_code 二选一；language_name 与 language_code 二选一。

请求示例 ​

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,
      "include_clickstream_data": false,
      "tag": "keyword-volume-demo"
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_search_volume/live"

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

payload = [
    {
        "keywords": ["phone", "watch"],
        "location_name": "United States",
        "language_name": "English",
        "include_serp_info": True,
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"信息：{result.get('status_message')}"
    )

TypeScript ​

typescript
import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_search_volume/live",
  [
    {
      keywords: ["phone", "watch"],
      language_name: "English",
      location_code: 2840,
      include_serp_info: true,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

if (response.data.status_code === 20000) {
  console.log(response.data);
} else {
  console.error(
    response.data.status_code,
    response.data.status_message
  );
}

响应结构 ​

响应为 JSON 对象，主要 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求级状态码。完整错误码请参考 /v3/appendix/errors。
status_messagestring请求级说明信息。
timestring请求执行时间，例如 0.1100 sec.。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorinteger返回错误的任务数量。
tasksarray任务结果数组。

任务字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常在 10000 至 60000 范围。
status_messagestring任务说明信息。
timestring任务执行时间。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求 URL 路径。
dataobject创建任务时提交的参数。
resultarray查询结果数组。

result 字段 ​

字段类型说明
se_typestring搜索引擎类型，通常为 google。
location_codeinteger请求中使用的地区代码。
language_codestring请求中使用的语言代码。
items_countintegeritems 数组中的结果数量。
itemsarray及指标。

items 字段 ​

基础字段 ​

字段类型说明
se_typestring搜索引擎类型。
keywordstring返回的。经过 URL 编码的字符会被解码，字符 + 会被解码为空格。
location_codeinteger | null地区代码。没有对应数据时为 null。
language_codestring语言代码。
search_partnersboolean是否 Google 合作伙伴网站的数据。true 表示 Google 自有、运营及合作伙伴网络；false 表示返回 Google 搜索网站数据。

keyword_info ​

的 Google Ads 指标。

字段类型说明
se_typestring搜索引擎类型。
last_updated_timestring指标更新时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
competitionfloat付费搜索竞争度，取值范围为 0 到 1，边界值。
competition_levelstring | null付费 SERP 竞争等级，可取 LOW、MEDIUM、HIGH；未知时为 null。
cpcfloat历史平均每次点击费用。
search_volumeintegerGoogle 月均搜索量估算值。
low_top_of_page_bidfloat广告展示在首页顶部所需的低位出价估算值，约高于最低出价的 20%。
high_top_of_page_bidfloat广告展示在首页顶部所需的高位出价估算值，约高于最低出价的 80%。
categoriesarray产品和服务类别。
monthly_searchesarray最近 12 个月的月度搜索量。
search_volume_trendobject搜索量趋势变化。
search_volume_trend.monthlyinteger相较上个月的搜索量变化百分比。
search_volume_trend.quarterlyinteger相较上一季度的搜索量变化百分比。
search_volume_trend.yearlyinteger相较上一年的搜索量变化百分比。

monthly_searches 数组中的：

字段类型说明
yearinteger年份。
monthinteger月份。
search_volumeinteger该月的平均搜索量估算值。

keyword_properties ​

的附加属性。

字段类型说明
se_typestring搜索引擎类型。
core_keywordstring | null同义词分组中的核心。如果为 null，表示未识别出与当前同义的。
synonym_clustering_algorithmstring | null同义词聚类算法。keyword_metrics 表示基于指标，text_processing 表示基于文本处理；无法识别时为 null。
keyword_difficultyinteger自然搜索结果前 10 名的难度，范围为 0 至 100，数值越高表示难度越大。
detected_languagestring系统识别出的语言。
is_another_languageboolean识别语言是否与请求语言不同。true 表示不同。

serp_info ​

当 include_serp_info 为 true 且数据库中存在该的 SERP 数据时返回；否则为 null。

字段类型说明
se_typestring搜索引擎类型。
check_urlstring可直接访问的搜索结果页 URL，可用于核验结果。
serp_item_typesarraySERP 中出现的结果类型。
se_results_countstring该的搜索结果数量。
last_updated_timestringSERP 数据更新时间，UTC 格式。
previous_updated_timestring上一次 SERP 数据更新时间，UTC 格式。

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

返回该自然排名前 10 个网站的平均外链指标和平均排名指标。

字段类型说明
se_typestring搜索引擎类型。
backlinksfloat平均外链数量。
dofollowfloat平均 Dofollow 链接数量。
referring_pagesfloat平均引用页面数量。
referring_domainsfloat平均引用域名数量。
referring_main_domainsfloat平均引用主域名数量。
rankfloat平均排名值。
main_domain_rankfloat平均主域名排名值。
last_updated_timestring外链数据更新时间，UTC 格式。

clickstream_keyword_info ​

只有将 include_clickstream_data 设置为 true 时才返回。

字段类型说明
search_volumeinteger基于点击流数据的月均搜索量。
last_updated_timestring点击流数据集更新时间，UTC 格式。
gender_distributionobject按性别划分的点击流指标估算分布。
gender_distribution.femaleinteger点击流数据集中的女性用户数量。
gender_distribution.maleinteger点击流数据集中的男性用户数量。
age_distributionobject按年龄划分的点击流指标估算分布。
age_distribution.18-24integer18 至 24 岁用户数量。
age_distribution.25-34integer25 至 34 岁用户数量。
age_distribution.35-44integer35 至 44 岁用户数量。
age_distribution.45-54integer45 至 54 岁用户数量。
age_distribution.55-64integer55 至 64 岁用户数量。
monthly_searchesarray按月份记录的点击流搜索量。

clickstream_keyword_info.monthly_searches素：

字段类型说明
yearinteger年份。
monthinteger月份。
search_volumeinteger该月份基于点击流数据的搜索量。

keyword_info_normalized_with_bing ​

使用 Bing 搜索量进行归一化后的指标。在 include_clickstream_data 为 true 时返回。

字段类型说明
last_updated_timestring数据集更新时间，UTC 格式。
search_volumeinteger当前归一化搜索量。
is_normalizedboolean是否已使用 Bing 数据进行归一化。
monthly_searchesarray归一化后的月度搜索量。

monthly_searches素：

字段类型说明
yearinteger年份。
monthinteger月份。
search_volumeinteger该月份的归一化搜索量。

keyword_info_normalized_with_clickstream ​

使用点击流数据进行归一化后的指标。在 include_clickstream_data 为 true 时返回。

字段类型说明
last_updated_timestring数据集更新时间，UTC 格式。
search_volumeinteger当前归一化搜索量。
is_normalizedboolean是否已使用点击流数据进行归一化。
monthly_searchesarray归一化后的月度搜索量。

monthly_searches素：

字段类型说明
yearinteger年份。
monthinteger月份。
search_volumeinteger该月份的归一化搜索量。

响应示例 ​

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": [
    {
      "id": " task-uuid",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0900 sec.",
      "cost": 0.0102,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "historical_search_volume",
        "live"
      ],
      "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": [
        {
          "se_type": "google",
          "location_code": 2840,
          "language_code": "en",
          "items_count": 1,
          "items": [
            {
              "se_type": "google",
              "keyword": "phone",
              "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": [
                  {
                    "year": 2024,
                    "month": 7,
                    "search_volume": 450000
                  }
                ],
                "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",
                "serp_item_types": ["organic", "paid", "people_also_ask"],
                "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": null,
              "keyword_info_normalized_with_clickstream": null
            }
          ]
        }
      ]
    }
  ]
}

错误处理 ​

建议根据请求级和任务级的 status_code、status_message 分别处理异常：

  • status_code = 20000：请求或任务成功。
  • 状态码：请求或任务失败，应记录错误码和错误信息，并根据业务需要重试或跳过。
  • 完整状态码列表请参考 /v3/appendix/errors。

实用场景 ​

  • 评估季节性：对比月度、季度和年度搜索量趋势，安排发布与促销活动的最佳时间。
  • 筛选付费搜索词：结合 competition、competition_level 和 CPC 指标，识别搜索需求高且投放成本可控的。
  • 规划多地区 SEO：按地区和语言批量获取历史搜索量，为不同国家或市场制定策略。
  • 分析 SERP 竞争环境：启用 include_serp_info，识别目标词的自然结果、广告、精选摘要和本地结果等页面特征。
  • 评估自然排名难度：结合 keyword_difficulty 与 avg_backlinks_info，判断 Google 自然结果前 10 名所需的和外链资源。

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

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