Google Ads 数据 API 概览

Google Ads 数据 API 用于获取分析所需的搜索量、建议及广告流量等数据。

> 容性说明： Google AdWords Keywords Data API 已 legacy 状态，建议迁移至 Google Ads API。本文保留原有 /v3/keywords_data/google/... 容路径，便于现有系统继续调用。

本组接口以下能力：

搜索量：/v3/keywords_data/google/search_volume/live/
网站：/v3/keywords_data/google/keywords_for_site/live/
扩展：/v3/keywords_data/google/keywords_for_keywords/live/
分类：/v3/keywords_data/google/keywords_for_category/live/
按获取广告流量：/v3/keywords_data/google/ad_traffic_by_keywords/live/
按平台获取广告流量：/v3/keywords_data/google/ad_traffic_by_platforms/live/

完整接口列表可参考：

/v3/keywords_data/endpoints/
/v3/keywords_data/google/languages/
/v3/keywords_data/google/locations/

数据范围与限制

返回结果会根据请求中的以下参数确定：

language：目标语言
location：目标国家、地区或城市

支持的地域范围与 Google 地理定位范围保持一致。数据通常会在每月中旬更新，如需确认上月数据是否已更新，可调用：

/v3/keywords_data/google/adwords_status/

受广告政策限制，以下类型的可能无法返回数据：

武器
烟草
药物
暴力
恐怖主义
受限制或禁止投放广告的类别

因此，对于部分，接口可能不返回搜索量或广告数据。

请求方式与任务模式

数据接口支持两种主要任务执行方式：Live 实时模式和Standard 标准模式。

Live 实时模式

Live 模式适用于需要即时获取结果的场景。调用对应的 Live 接口后，系统会直接在响应中返回处理结果，无需再分别执行任务创建和结果查询请求。

型路径示例：

text

/v3/keywords_data/google/search_volume/live/

Standard 标准模式

Standard 模式适用于不要求实时返回结果的场景，通常成本更低。该模式需要分两步执行：

通过 POST 请求创建任务；
通过 GET 请求查询任务结果。

当系统完成数据采集后，即可获取任务结果。

回调通知

创建任务时，可以指定以下回调参数：

pingback_url：任务完成后向指定地址发送通知；
postback_url：任务完成后将结果发送到指定地址。

如果一次提交多个任务，可以使用任务就绪接口获取已完成任务的 id 列表，再通过任务查询接口分别获取每个任务的详细结果。

请求格式

所有 POST 请求体均使用 JSON 数组格式，即使只提交一个任务，也需要将对象放数组中：

json

[
  {
    "language_code": "en",
    "location_code": 2840,
    "keywords": [
      "seo tools",
      "keyword research"
    ]
  }
]

认证示例：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

调用示例

以下示例以搜索量 Live 接口为例：

cURL

bash

curl --request POST \
  --url https://api.seermartech.cn/v3/keywords_data/google/search_volume/live/ \
  --header 'Authorization: Bearer smt_live_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "language_code": "en",
      "location_code": 2840,
      "keywords": [
        "seo tools",
        "keyword research"
      ]
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google/search_volume/live/"

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

payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keywords": [
            "seo tools",
            "keyword research",
        ],
    }
]

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

# 输出接口返回结果
print(response.json())

TypeScript

typescript

const response = await fetch(
  "https://api.seermartech.cn/v3/keywords_data/google/search_volume/live/",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify([
      {
        language_code: "en",
        location_code: 2840,
        keywords: ["seo tools", "keyword research"],
      },
    ]),
  }
);

// 输出接口返回结果
const result = await response.json();
console.log(result);

频率限制

平台限流以认证说明中的 30/60/120 次/分钟规则为准**。如需提高调用频率限制，请联系平台技术支持。

计费说明

接口费用取决于以下因素：

使用的任务模式；
调用的接口；
任务执行优级。

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

你可以使用沙箱环境测试数据接口：

/v3/appendix/sandbox/

实用场景

评估目标的搜索需求：批量获取搜索量数据，为 SEO 筛选、优级排序和投放预算分提供依据。
分析竞争网站的覆盖：通过网站接口提取目标站点词，发现缺口和潜在流量。
扩展词库：根据种子获取，用于搭建主题集群、规划长尾和完善站结构。
按行业分类挖掘：基于分类获取细分领域词库，支持行业市场调研和专题页规划。
比较不同广告平台的流量：获取或平台维度的广告流量数据，评估投放渠道和广告策略。

Google Ads 数据 API 概览 ​

数据范围与限制 ​

请求方式与任务模式 ​

Live 实时模式 ​

Standard 标准模式 ​

回调通知 ​

请求格式 ​

调用示例 ​

cURL ​

Python ​

TypeScript ​

频率限制 ​

计费说明 ​

实用场景 ​