SeerMarTech API 文档

主题

Google 历史数据 ​

POST /v3/dataforseo_labs/google/historical_keyword_data/live

本接口使用 POST 方法，请求路径为：

/v3/dataforseo_labs/google/historical_keyword_data/live

用于查询指定在 Google 上的历史数据搜索量、每次点击费用（CPC）、付费搜索竞争度、月度搜索量以及搜索量趋势。根据、地区和语言组合的不同，历史数据最早可追溯至 2021 年 8 月。

数据来源为数据库，基础数据来自 Google Ads API。数据源完成更新后，本平台通常每月更新一次指标。由于 Google 可能重新调整某个月份的搜索量，本接口也会同步更新对应历史值。

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

/v3/dataforseo_labs/locations_and_languages

请求说明 ​

  • 请求方法：POST
  • 请求体格式：UTF-8 编码的 JSON 数组
  • 每次 Live API 调用只能提交一个任务，因此请求数组中通常只一个对象 平台限流以认证说明中的 30/60/120 次/分钟规则为准
  • 同时进行的请求数最多为 30 个
  • 单个任务最多 700 个
  • 对于数据库中不存在、未在结果中返回的，不收取对应费用
  • 会被转换为小写，并在结果中以独立数组返回

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

请求参数 ​

请求体是 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。
tagstring否自定义任务标识，用于将请求与结果匹。最长 255 个字符。传的值会在响应的 data 对象中返回。

> location_name 与 location_code 至少提供一个；language_name 与 language_code 至少提供一个。

请求示例 ​

json
[
  {
    "keywords": [
      "iphone",
      "best iphone"
    ],
    "location_name": "United States",
    "language_name": "English",
    "tag": "keyword-history-demo"
  }
]

响应结构 ​

接口返回 JSON 对象 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求级状态码。完整状态码列表请参考错误码文档。
status_messagestring请求级提示信息。
timestring接口执行耗时，单位为秒。
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请求路径信息。
dataobject请求中提交的参数。
resultarray查询结果数组。

result 字段 ​

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

items 字段 ​

字段类型说明
se_typestring搜索引擎类型。
keywordstring。返回值会对 URL 编码进行解码；例如 %## 会被解码，字符 + 会被解码为空格。
location_codeinteger / null请求中的地区代码。没有对应数据时为 null。
language_codestring请求中的语言代码。
historyarray该的历史数据，按年月多个对象。

history 字段 ​

字段类型说明
yearinteger数据年份。
monthinteger数据月份，取值为 1 至 12。
keyword_infoobject该月份的指标。

keyword_info 字段 ​

字段类型说明
se_typestring搜索引擎类型。
last_updated_timestring数据更新时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
competitionfloat付费搜索竞争度，基于 Google Ads 数据，取值范围为 0 至 1（含边界）。
competition_levelstring / null付费搜索结果中的竞争等级，可取 LOW、MEDIUM、HIGH；未知时为 null。
cpcfloat历史平均每次点击费用。
search_volumeinteger平均月搜索量，表示 Google 搜索中该的大致搜索次数。
low_top_of_page_bidfloat / null广告展示在首页顶部所需的较低出价参考值。通常高于历史最低展示出价的约 20%，值可能因地区不同而变化。
high_top_of_page_bidfloat / null广告展示在首页顶部所需的较高出价参考值。通常高于历史最低展示出价的约 80%，值可能因地区不同而变化。
categoriesarray对应的商品和服务类别。
monthly_searchesarray过去 12 个月的月度搜索量数据，按请求指定的地理位置统计。
search_volume_trendobject搜索量趋势变化，表示相对于上一统计周期的百分比变化。

monthly_searches 字段 ​

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

search_volume_trend 字段 ​

字段类型说明
monthlyinteger相比上个月的搜索量变化百分比。
quarterlyinteger相比上一季度的搜索量变化百分比。
yearlyinteger / null相比上一年度的搜索量变化百分比。历史数据不足时可能为 null。

响应示例 ​

以下示例展示一个及两个历史月份的部分结果：

json
{
  "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": "2f6f7f1e-7b9a-4d1e-9f2a-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 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"
        ],
        "tag": "keyword-history-demo"
      },
      "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": [
                      {
                        "year": 2025,
                        "month": 1,
                        "search_volume": 1220000
                      }
                    ],
                    "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": [
                      {
                        "year": 2024,
                        "month": 12,
                        "search_volume": 1220000
                      }
                    ],
                    "search_volume_trend": {
                      "monthly": 23,
                      "quarterly": 23,
                      "yearly": 23
                    }
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

请求成功时，顶层或任务级 status_code 通常为 20000。生产环境应根据状态码和 tasks_error 实现异常处理。

调用示例 ​

cURL ​

bash
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"],
      "location_name": "United States",
      "language_name": "English"
    }
  ]'

Python ​

python
import requests

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

payload = [
    {
        "keywords": ["iphone"],
        "location_name": "United States",
        "language_name": "English"
    }
]

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

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：{}，信息：{}".format(
            result.get("status_code"),
            result.get("status_message")
        )
    )

TypeScript ​

typescript
import axios from "axios";

const payload = [
  {
    keywords: ["iphone"],
    location_name: "United States",
    language_name: "English",
    tag: "keyword-history-demo",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_keyword_data/live",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `请求失败，状态码：${result.status_code}，信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络或服务异常：", error.message);
  });

PHP ​

php
<?php

$url = 'https://api.seermartech.cn/v3/dataforseo_labs/google/historical_keyword_data/live';

$payload = [
    [
        'keywords' => ['iphone'],
        'location_name' => 'United States',
        'language_name' => 'English'
    ]
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE)
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

实用场景 ​

  • 回溯目标的历史搜索量，识别长期增长或衰退趋势，为规划和年度 SEO 预算分提供依据。
  • 比较不同月份的 CPC 与付费竞争度，筛选自然流量潜力高且商业价值明确的。
  • 监测的季节性波动，结合月度搜索量提前安排专题页、促销页和发布时间。
  • 分析地区与语言组合下的表现，为多地区、多语言站点制定本地化策略。
  • 评估搜索量异常变化，通过月度、季度和年度趋势指标发现需求变化，并及时调整布局。

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

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