Google Ads 搜索 API 概览

本接口通过 POST /v3/serp/google/ads_search/task_post/ 创建采集任务，并通过 GET /v3/serp/google/ads_search/task_get/advanced/ 获取结果。它基于 Google Ads Transparency 数据，返回指定广告主或目标域名在 Google Ads 平台投放的广告搜索结果。

接口返回的数据可按以下条件查询：

• advertiser_id：广告主唯一标识，可通过 /v3/serp/google/ads_advertisers/task_get/advanced/ 获取。
• target：目标网站域名，用于查询与该域名的广告投放信息。

> 注意：Google Ads 搜索接口支持 desktop 设备类型和 windows 操作系统。

功能说明

Google Ads 搜索高级结果

GET /v3/serp/google/ads_search/task_get/advanced/ 可返回指定查询条件下最多 40 条搜索结果及广告数据。

结果中以下排名字段：

字段	说明
rank_group	素在所属结果分组中的排名。
rank_absolute	素在整个搜索结果页中的绝对排名。

例如，广告位、自然搜索结果、知识面板等可能属于不同的结果分组；rank_group 描述组位置，rank_absolute 描述在整个 SERP 页面中的总体位置。

调用方式

Google Ads 搜索接口支持标准任务模式。该模式需要提交任务，再在任务完成后获取结果。

1. 创建任务

使用以下接口提交一个或多个任务：

POST /v3/serp/google/ads_search/task_post/

每次 POST 请求最多可 100 个任务，请求体为 JSON 数组。

curl -X POST "https://api.seermartech.cn/v3/serp/google/ads_search/task_post/" \
  -H "Authorization: Bearer smt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "advertiser_id": "ADVERTISER_ID",
      "location_name": "United States",
      "language_name": "English",
      "depth": 40
    }
  ]'

Python 示例

import requests

url = "https://api.seermartech.cn/v3/serp/google/ads_search/task_post/"

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

# POST 请求体是任务数组
payload = [
    {
        "advertiser_id": "ADVERTISER_ID",
        "location_name": "United States",
        "language_name": "English",
        "depth": 40,
    }
]

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

TypeScript 示例

const response = await fetch(
  "https://api.seermartech.cn/v3/serp/google/ads_search/task_post/",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    // POST 请求体是任务数组
    body: JSON.stringify([
      {
        advertiser_id: "ADVERTISER_ID",
        location_name: "United States",
        language_name: "English",
        depth: 40,
      },
    ]),
  }
);

const result = await response.json();
console.log(result);

创建任务后，响应中会返回任务 id。请保存该标识，用于后续查询任务结果。

2. 获取任务结果

任务完成后，使用任务 ID 获取高级搜索结果：

GET /v3/serp/google/ads_search/task_get/advanced/{task_id}

curl -X GET "https://api.seermartech.cn/v3/serp/google/ads_search/task_get/advanced/TASK_ID" \
  -H "Authorization: Bearer smt_live_YOUR_KEY"

，TASK_ID 为创建任务时返回的任务标识。

3. 获取已完成任务列表

当批量提交多个任务时，可通过以下接口获取已完成任务的 ID 列表：

GET /v3/serp/google/ads_search/tasks_ready/

随后，针对每个已完成任务调用：

GET /v3/serp/google/ads_search/task_get/advanced/{task_id}

获取对应结果。

4. 使用回调接收结果

创建任务时可选填以下回调字段：

字段	说明
pingback_url	任务完成后，本平台向该 URL 发送完成通知。收到通知后，您仍需调用结果获取接口拉取数据。
postback_url	任务完成后，本平台将结果直接推送至该 URL。使用此字段时会返回 advanced 类型结果。

回调地址应可从访问，并能够正确处理本平台发送的 HTTP 请求。

执行优级与计费

标准任务模式支持两种执行优级：

优级	说明
normal	常规执行优级，适合对时效性要求一般的批量采集任务。
high	高优级执行，适合需要更快获取结果的场景。

任务费用受执行优级及 depth 参数影响。

默认结果深度为 40。若设置的 depth过默认深度，将按每 40 条结果为一个计费单位计算。例如：

• depth: 40：按 40 条结果计费；
• depth: 45：按 80 条结果计费，即费用为默认深度对应费用的 2 倍。

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

调用限制

限制项	说明
API 调用频率平台限流以认证说明中的 30/60/120 次/分钟规则为准/分钟。
单次 POST 任务数	单个 POST 请求最多提交 100 个任务。
支持的平台	支持 desktop 与 windows。
最大结果深度	高级结果接口默认最多返回前 40 条结果；提高 depth 会影响计费。

如需更高并发或任务提交额度，请联系本平台技术支持。

接口

接口	用途
GET /v3/serp/google/ads_advertisers/task_get/advanced/	获取广告主信息及可用于搜索的 advertiser_id。
POST /v3/serp/google/ads_search/task_post/	创建 Google Ads 搜索任务。
GET /v3/serp/google/ads_search/task_get/advanced/{task_id}	获取指定任务的高级搜索结果。
GET /v3/serp/google/ads_search/tasks_ready/	获取已完成任务列表。
/v3/appendix/sandbox/	在沙箱环境中测试接口调用。

实用场景

• 监测竞品广告投放：按 advertiser_id 查询竞争对手的广告展示，识别投放策略、重点市场与广告覆盖范围。
• 核查品牌域名投放：按 target 域名检索广告，确认自有品牌或合作站点是否存在未授权、误导性或冲突投放。
• 分析行业广告竞争度：结合不同地区、语言和搜索条件采集广告结果，评估目标市场中的付费搜索竞争强度。
• 追踪广告位变化：定期获取 rank_group 与 rank_absolute，分析广告结果在搜索页中的位置变化及展示稳定性。
• 构建竞品报看板：批量提交广告主查询任务并通过回调接收结果，为市场、SEO 与投放团队提供持续更新的广告监测数据。