Google Ads 数据 API 概览

Google Ads 数据 API 用于获取搜索量、广告竞争度、点击成本、预估流量等研究数据。数据来源于 Google Ads API，返回结果取决于 POST 请求中指定的、地区、语言和参数。

本 API 支持以下核心能力：

通过 /v3/keywords_data/google_ads/search_volume/live/ 查询最多 1,000 个的搜索量及指标。
通过 /v3/keywords_data/google_ads/keywords_for_site/live/ 指定一个域名，获取最多 2,000 个。
通过 /v3/keywords_data/google_ads/keywords_for_keywords/live/ 指定最多 20 个种子词，获取最多 20,000 个建议。
通过 /v3/keywords_data/google_ads/ad_traffic_by_keywords/live/ 查询最多 1,000 个的广告展示量、每次点击成本（CPC）和点击量数据。
通过 /v3/keywords_data/google_ads/status/ 检查上一个月份的数据是否已更新。

可用端点列表请参考 /v3/keywords_data/endpoints/。

数据范围与限制

支持的地区范围与 Google Ads 地理位置定向保持一致。请求中应使用平台支持的地区代码和语言代码，以获得对应市场的数据。

数据通常会在每月中旬更新。建议在需要月度数据更新确认时调用：

/v3/keywords_data/google_ads/status/

受广告政策限制，以下或类似敏感类别的可能无法返回数据：

武器及危险品
烟草及产品
毒品及违禁药物
暴力
恐怖主义
受广告投放政策限制的类别

当响应中未返回搜索量或指标时，除本身搜索量较低外，也可能是由于属于受限类别。

任务执行方式

数据接口支持两种结果获取方式：实时（Live） 和 标准任务（Standard）。

实时方式（Live）

实时方式适用于需要立即获取结果的业务场景。调用 Live 接口后，平台会在同一次请求响应中返回结果，无需分别创建任务和轮询任务结果。

常用实时端点：

/v3/keywords_data/google_ads/search_volume/live/
/v3/keywords_data/google_ads/keywords_for_site/live/
/v3/keywords_data/google_ads/keywords_for_keywords/live/
/v3/keywords_data/google_ads/ad_traffic_by_keywords/live/

> 注意：Google Ads Live 端点每个账户最多支持每分钟 12 次请求。

标准任务方式（Standard）

标准任务方式适用于不要求即时返回结果、需要降低调用成本或需要批量处理大量请求的场景。

标准流程通常：

使用 POST 请求创建任务。
等平台采集并处理数据。
使用任务 GET 接口获取指定任务的结果。

创建任务时，还可以指定以下回调字段：

pingback_url：任务完成后向指定地址发送完成通知。
postback_url：任务完成后将结果直接推送至指定地址。

如果一次创建了多个任务，可以通过 Tasks Ready 接口获取已完成任务的 id 列表，再使用对应的 Task GET 接口逐个拉取结果。

POST 请求体应使用 JSON 数组格式，即使提交一个任务也应放在数组中：

json

[
  {
    "keywords": [
      "seo 工",
      "分析"
    ],
    "location_code": 2156,
    "language_code": "zh"
  }
]

请求频率限制

除 Live 接口的单独限制外，账户级 API 调用总频率上限为：

最多 2,000 次 API 调用 / 分钟
Google Ads Live 端点最多 12 次请求 / 分钟 / 账户

如需提高调用频率，请联系平台技术支持评估额度。

对于大批量请求，建议：

将按端点的最大数量拆分批次。
对实时请求实施限流和重试机制。
对标准任务使用 pingback_url 或 postback_url，减少轮询请求。
优通过 Tasks Ready 接口筛选已完成任务，再拉取结果。

计费说明

数据接口的费用取决于所调用的端点、任务执行方式、数量及请求参数。

实时方式通常适合低延迟查询；标准任务方式通常更适合大规模、非实时的数据采集。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

可通过以下接口查看账户余额、消费和使用信息：

/v3/appendix/user_data/

如需在正式调用前验证请求格式和响应结构，可使用沙箱环境：

/v3/appendix/sandbox/

实用场景

筛选高潜力：批量查询搜索量、CPC 和竞争指标，识别备自然流量或广告投放价值的。
挖掘竞品机会：竞品域名获取，发现布局、SEO 覆盖和广告投放机会。
扩展长尾词库：基于核心产品词或行业词获取建议，快速构建选题和落地页单。
评估广告投放预算：查询展示量、点击量和 CPC，预估搜索广告预算及获客成本。
监控月度数据更新：定期调用状态接口确认数据月份，确保报表、趋势分析和决策使用最新数据。

Google Ads 数据 API 概览 ​

数据范围与限制 ​

任务执行方式 ​

实时方式（Live） ​

标准任务方式（Standard） ​

请求频率限制 ​

计费说明 ​

实用场景 ​