Google Ads 广告主 API：概览

本接口用于获取 Google Ads 广告透明度搜索结果中的广告主数据。核心任务接口契约如下：

• POST /v3/serp/google/ads_advertisers/task_post/：提交广告主数据采集任务
• GET /v3/serp/google/ads_advertisers/tasks_ready/：获取已完成任务的 ID 列表
• GET /v3/serp/google/ads_advertisers/task_get/advanced/：获取指定任务的详细结果

功能概述

本接口基于 Google Ads Transparency 数据，返回在 Google Ads 平台投放广告的广告主信息。

返回结果与请求中的以下参数：

• keyword：搜索
• location：搜索位置

> **注意：**本接口支持 desktop 和 windows 设备类型。

SERP 排名字段

SERP 结果使用以下字段表示排名：

• rank_group：在所属结果分组中的排名
• rank_absolute：在整个 SERP 结果中的绝对排名

例如，某个广告可能在广告结果分组中排名第 2，但在整个 SERP 页面所有中排名第 5。此时：

{
  "rank_group": 2,
  "rank_absolute": 5
}

数据获取方式

本接口支持 Standard（标准） 数据获取方式。该方式需要分两个阶段完成：

1. 使用 POST 接口提交任务；
2. 等系统完成采集后，使用 GET 接口获取结果。

提交任务

向以下接口提交任务：

POST /v3/serp/google/ads_advertisers/task_post/

请求体为 JSON 数组，每个请求最多 100 个任务：

[
  {
    "keyword": "示例",
    "location_code": 2840,
    "device": "desktop",
    "os": "windows"
  }
]

获取已完成任务

如果需要批量处理多个任务，可以调用以下接口获取已完成任务的 ID：

GET /v3/serp/google/ads_advertisers/tasks_ready/

随后，针对每个任务调用以下接口获取详细结果：

GET /v3/serp/google/ads_advertisers/task_get/advanced/

使用回调通知

提交任务时，可以选择以下回调地址：

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

> **注意：**如果使用 postback_url，系统支持通过 advanced 函数返回数据。

请求限制

平台限流以认证说明中的 30/60/120 次/分钟规则为准POST 和 GET API 调用。

此外：

• 每次 POST 请求最多提交 100 个任务；
• 如需提高调用额度，请联系平台技术支持。

执行优级与计费

Standard 方法支持以下两种任务优级：

1. Normal priority：普通优级
2. High priority：高优级

优级会影响任务执行速度，不同优级的计费标准可能不同。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

认证示例

curl --request POST \
  --url https://api.seermartech.cn/v3/serp/google/ads_advertisers/task_post/ \
  --header 'Authorization: Bearer smt_live_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "keyword": "示例",
      "location_code": 2840,
      "device": "desktop",
      "os": "windows"
    }
  ]'

##测试

可以通过以下沙箱接口测试本接口能力：

/v3/appendix/sandbox/

实用场景

• 监测竞争对手广告主：根据目标和地区识别正在投放广告的企业，支持竞品广告报分析。
• 分析搜索广告竞争格局：统计不同下的广告主分布，评估市场竞争强度和广告位竞争。
• 发现潜在客户：筛选持续投放搜索广告的企业，为销售拓客和广告营销服务提供客户线索。
• 比较不同地区的广告主：按位置对比广告主覆盖，制定区域化 SEO 与 SEM 策略。
• 跟踪广告主变化：定期提交相同与位置的任务，识别新增、退出或持续投放的广告主。