Google Ads 搜索实时高级接口

GET /v3/serp/google/ads_search/locations

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

/v3/serp/google/ads_search/live/advanced

Google Ads 搜索接口用于获取广告主在 Google Ads 上投放的广告信息。数据基于广告透明度平台信息，并经过整理后返回。本接口支持按指定地点、广告主、广告平台、广告格式及时间范围查询广告数据。

历史数据最早可追溯至 2018-05-31。

> 注意：每个 SERP 最多返回 40 条结果，并按每个 SERP 计费。单次 Live SERP 请求只能提交一个任务；平台限流以认证说明中的 30/60/120 次/分钟规则为准。

计费说明

每个请求单独计费。
默认解析深度为 40；当 depth过 40 且搜索引擎返回 40 条结果时，可能产生额外费用。
设置 priority=2（高优级）会产生额外费用。
参考价约 ¥0.0144 / 次，价格以账户及返回结果为准。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有请求体使用 UTF-8 编码的 JSON 数组格式：

json

[
  {
    "location_code": 2840,
    "platform": "google_search",
    "advertiser_ids": [
      "AR13752565271262920705",
      "AR02439908557932462081"
    ]
  }
]

请求参数

主要参数

参数	类型	填	说明
`location_code`	integer	否	搜索引擎地点代码。使用此参数后，无需再指定 `location_name` 或 `location_coordinate`。可通过 `/v3/serp/google/ads_search/locations` 获取可用地点代码。示例：`2840`。如果未指定地点参数，则会在所有可用地点中搜索广告。
`depth`	integer	否	解析深度，即 SERP 结果数量。默认值为 `40`，最大值为 `120`。每 40 条结果为一个计费单位， 40 可能产生额外费用。
`target`	string	条件填	广告主的域名。当未指定 `advertiser_ids` 时填。
`advertiser_ids`	array	条件填	广告主标识符。当未指定 `target` 时填，最多可传 25 个值。广告主标识符可通过 Google Ads 广告主接口获取。
`priority`	integer	否	任务优级：`1` 表示普通优级（默认），`2` 表示高优级。高优级任务会产生额外费用。

target 和 advertiser_ids 至少需要指定一个。

附加参数

参数	类型	填	说明
`location_name`	string	否	搜索引擎地点的完整名称。使用此参数后，无需指定 `location_code` 或 `location_coordinate`。示例：`London,England,United Kingdom`。如果未指定地点参数，则会在所有可用地点中搜索广告。
`location_coordinate`	string	否	地点 GPS 坐标，格式为 `纬度,经度`。示例：`52.6178549,-155.352142`。使用此参数后，无需指定 `location_name` 或 `location_code`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样出现在响应的 `data` 对象中，可用于请求和结果。
`platform`	string	否	广告投放平台。可选值：`all`、`google_play`、`google_maps`、`google_search`、`google_shopping`、`youtube`。默认值：`all`。
`format`	string	否	广告格式。可选值：`all`、`text`、`image`、`video`。
`date_from`	string	条件填	查询时间范围的开始日期。指定 `date_to` 时填。格式：`yyyy-mm-dd`，最早为 `2018-05-31`，最晚为当前日期。
`date_to`	string	条件填	查询时间范围的结束日期。指定 `date_from` 时填。格式：`yyyy-mm-dd`，最早为 `2018-05-31`，最晚为当前日期。

location_code、location_name 和 location_coordinate 用于指定查询地点，三最多使用一个。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/google/ads_search/live/advanced" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_code": 2840,
      "platform": "google_search",
      "advertiser_ids": [
        "AR13752565271262920705",
        "AR02439908557932462081"
      ]
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "location_code": 2840,
        "platform": "google_search",
        "advertiser_ids": [
            "AR13752565271262920705",
            "AR02439908557932462081",
        ],
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败：{result.get('status_code')} "
        f"{result.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/serp/google/ads_search/live/advanced",
  [
    {
      location_code: 2840,
      platform: "google_search",
      advertiser_ids: [
        "AR13752565271262920705",
        "AR02439908557932462081",
      ],
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

const result = response.data;

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(
    `请求失败：${result.status_code} ${result.status_message}`
  );
}

响应结构

接口返回 JSON 数据，主要结构如下：

json

{
  "version": "0.1.20241203",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "9.1262 sec.",
  "cost": 0.002,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "9.1262 sec.",
      "cost": 0.002,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "google",
        "ads_search",
        "live",
        "advanced"
      ],
      "data": {
        "api": "serp",
        "function": "live",
        "se": "google",
        "se_type": "ads_search",
        "location_code": 2840,
        "platform": "google_search",
        "advertiser_ids": [
          "AR13752565271262920705",
          "AR02439908557932462081"
        ],
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "se_results_count": 0,
          "items_count": 37,
          "items": []
        }
      ]
    }
  ]
}

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求总体状态码。成功通常为 `20000`。完整错误码请参考错误码文档。
`status_message`	string	请求总体状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态信息。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求 API 的路径片段。
`data`	object	请求中提交的参数。
`result`	array	SERP 查询结果数组。

`result` 结果字段

字段	类型	说明
`keyword`	string	请求中的。返回时会对编码进行解码，`+` 会被解码为空格。
`type`	string	搜索引擎结果类型。
`se_domain`	string	搜索引擎域名。
`location_code`	integer	地点代码。
`language_code`	string	语言代码。
`check_url`	string \| null	搜索引擎结果页的直接 URL。本接口通常为 `null`。
`datetime`	string	获取结果的日期和时间，采用 UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`spell`	object \| null	搜索引擎自动纠错信息。如果被纠正，则返回纠正后的及纠错类型；无纠错时为 `null`。
`refinement_chips`	object	搜索细化选项。
`item_types`	array	SERP 中的结果类型。本接口可能 `ads_search`。
`se_results_count`	integer	SERP 中的结果总数。
`items_count`	integer	`items` 数组中返回的结果数量。
`items`	array	SERP 结果数组。

`refinement_chips`

字段	类型	说明
`type`	string	固定为 `refinement_chips`。
`xpath`	string	素在页面中的 XPath。
`items`	array	搜索细化列表。

refinement_chips.items 中的字段：

字段	类型	说明
`type`	string	固定为 `refinement_chips_element`。
`title`	string	细化选项标题。
`url`	string	携带细化参数的搜索 URL。
`domain`	string	SERP 中的域名。
`options`	array	进一步的搜索细化选项。

options 中的字段：

字段	类型	说明
`type`	string	固定为 `refinement_chips_option`。
`title`	string	细化选项标题。
`url`	string	携带细化参数的搜索 URL。
`domain`	string	SERP 中的域名。

`ads_search` 广告结果字段

当 items 中的类型为 ads_search 时，返回以下字段：

字段	类型	说明
`type`	string	固定为 `ads_search`。
`rank_group`	integer	分组排名。在相同 `type`素组成的分组中的位置；不同类型之间的位置不会计此字段。
`rank_absolute`	integer	SERP 中的绝对排名，即在所有结果中的位置。
`advertiser_id`	string	广告账户唯一标识符。
`creative_id`	string	广告创意唯一标识符。
`title`	string	广告标题，通常广告主名称。
`url`	string	广告 URL，指向广告透明度平台中的广告。
`verified`	boolean	广告账户是否经过验证。Google Ads 已验证账户时为 `true`。
`format`	string	广告格式。可选值：`text`、`image`、`video`。
`preview_image`	array	广告预览图信息。
`preview_url`	string	指向广告预览页面的 URL。
`first_shown`	string	广告首次展示时间，采用 UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`last_shown`	string	广告最近一次展示时间，采用 UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。

`preview_image` 字段

字段	类型	说明
`url`	string	预览图 URL。
`height`	integer	预览图高度。
`width`	integer	预览图宽度。

状态码与错误处理

请根据以下字段判断请求及任务是否成功：

顶层 status_code
任务级 tasks[].status_code
对应的 status_message

建议在客户端实现错误重试、参数校验、时处理及部分任务失败处理。完整状态码列表请参考错误码文档。

实用场景

监测竞品广告主：按 advertiser_ids 获取竞品在不同地区和平台投放的广告，分析广告素材、投放时间及覆盖范围。
追踪品牌广告：按 target 和地点查询指定域名的广告，评估品牌在目标市场中的广告可见度。
分析广告素材变化：结合 format、first_shown 和 last_shown 字段，识别文本、图片及视频广告的上线周期和更新频率。
构建地区广告报库：使用 location_code 或 location_coordinate 获取不同城市的广告结果，为区域市场策略和本地化 SEO 提供依据。
评估广告平台投放组合：通过 platform 区分 Google 搜索、购物、地图、应用商店和 YouTube 广告，比较竞品在各渠道的投放重点。

Google Ads 搜索实时高级接口 ​

计费说明 ​

请求参数 ​

主要参数 ​

附加参数 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 任务字段 ​

result 结果字段 ​

refinement_chips ​

ads_search 广告结果字段 ​

preview_image 字段 ​

状态码与错误处理 ​

实用场景 ​