Google Ads 搜索广告实时结果（高级版）

本接口用于获取 Google Ads 搜索广告结果，数据来源于广告透明度平台，并经过结构化处理，便于直接用于 SEO、竞品投放研究与广告报分析。

接口会根据指定地区及筛选条件返回广告主在 Google Ads 上投放的广告结果。支持按域名、广告主 ID、平台、广告格式、时间范围等条件过滤。

接口地址

POST https://api.seermartech.cn/v3/serp/google/ads_search/live/advanced

功能说明

返回指定条件下的 Google Ads 搜索广告结果
支持实时查询
支持历史数据，最早可追溯至 2018-05-31
单次 Live 请求支持提交 1 个任务
接口限速：最多 2000 次 API 调用/分钟
计费按每个 SERP 结果页计费，每个 SERP 最多 40 条结果

计费说明

本接口按请求计费。

若参考单价为 USD 0.002 / 次，则：

参考价约 ¥0.0320 / 次

当 depth过 40 且搜索引擎返回结果 40 条时，可能产生额外扣费。若使用高优级任务（priority = 2），也可能产生附加费用。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求体格式

所有 POST 数据使用 JSON（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`。注意：如果 `location_name`、`location_code`、`location_coordinate` 均未指定，则会在所有可用地区范围搜索广告。
`depth`	integer	解析深度，可选。表示返回的 SERP 结果数量。默认值：`40`；最大值：`120`。每 40 条结果按一个 SERP 计费；若设置大于 40，且返回 40 条，可能产生额外费用。
`target`	string	域名。若未指定 `advertiser_ids`，则该字段为填。表示与广告主账户的域名。
`advertiser_ids`	array	广告主标识符数组。若未指定 `target`，则该字段为填。最多支持传 25 个值。可通过 Google Ads Advertisers 接口获取广告主 ID。
`priority`	integer	任务优级，可选。可选值：`1` = 普通优级（默认），`2` = 高优级。高优级任务可能产生额外费用。

附加参数

字段名	类型	说明
`location_name`	string	搜索引擎地区名。可选。如果使用该字段，则无需传 `location_code` 或 `location_coordinate`。示例：`London,England,United Kingdom`。如果未指定任一地区参数，则会在所有可用地区范围搜索广告。
`tag`	string	自定义任务标识，可选，最长 255 个字符。可用于将请求与响应结果进行；返回结果中的 `data` 对象会该值。
`location_coordinate`	string	地理坐标，可选。如果使用该字段，则无需传 `location_name` 或 `location_code`。示例：`52.6178549,-155.352142`。如果未指定任一地区参数，则会在所有可用地区范围搜索广告。
`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`；最大值：当天日期。示例：`"2020-01-01"`
`date_to`	string	时间范围结束日期，可选。若指定 `date_from`，则该字段填。格式：`yyyy-mm-dd`。最小值：`2018-05-31`；最大值：当天日期。示例：`"2020-01-01"`

响应结构

接口返回 JSON 编码数据，顶层 tasks 数组，每个任务对应一个结果对象。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码，完整列表见 `/v3/appendix/errors`
`status_message`	string	通用状态信息，完整列表见 `/v3/appendix/errors`
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数
`tasks_error`	integer	返回错误的任务数
`tasks`	array	任务结果数组

tasks[] 字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`，完整列表见 `/v3/appendix/errors`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时，单位秒
`cost`	float	该任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	URL 路径
`data`	object	与请求中提交的参数一致
`result`	array	结果数组

result[] 字段

字段名	类型	说明
`keyword`	string	POST 数组中的。返回时会解码 `%##`，`+` 会被解码为空格。
`type`	string	POST 数组中的搜索引擎类型
`se_domain`	string	POST 数组中的搜索引擎域名
`location_code`	integer	POST 数组中的地区编码
`language_code`	string	POST 数组中的语言编码
`check_url`	string	搜索引擎结果直达链接；该接口中为 `null`
`datetime`	string	结果抓取时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`spell`	object	搜索引擎自动纠错信息；如无则为 `null`
`refinement_chips`	object	搜索细化条件块
`item_types`	array	本次 SERP 中出现的结果类型。当前可能：`ads_search`
`se_results_count`	integer	SERP 中的结果总数
`items_count`	integer	`items` 数组中的结果数量
`items`	array	返回的广告结果项

字段名	类型	说明
`type`	string	素类型，固定为 `refinement_chips`
`xpath`	string	素的 XPath
`items`	array	细化条件项

字段名	类型	说明
`type`	string	素类型，固定为 `refinement_chips_element`
`title`	string	条件标题
`url`	string	携带筛选参数的搜索 URL
`domain`	string	SERP 中的域名
`options`	array	更多筛选选项

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

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	广告预览页链接
`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	预览图链接
`height`	integer	预览图高度
`width`	integer	预览图宽度

请求示例

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"
}
data = [
 {
 "location_code": 2840,
 "platform": "google_search",
 "advertiser_ids": [
 "AR13752565271262920705",
 "AR02439908557932462081"
 ]
 }
]

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

TypeScript

typescript

import axios from "axios";

async function main {
 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"
 }
 }
 );

 console.log(response.data);
}

main.catch(console.error);

响应示例

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": [
 {
 "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": []
 }
 ]
 }
 ]
}

错误处理

建议在接时对以下两类状态进行处理：

顶层 status_code / status_message：表示整次请求的执行状态
tasks[].status_code / tasks[].status_message：表示单个任务的执行状态

完整错误码与状态说明请参考：

/v3/appendix/errors

常见处理建议：

校验 target 与 advertiser_ids 是否至少提供一个
校验 date_from 与 date_to 是否成对出现
校验 advertiser_ids 数量是否 25
校验 depth 是否最大值 120
记录返回中的 cost、time、id 便于审计与重试

使用建议

若已明确广告主账户，优使用 advertiser_ids，匹更稳定
若以品牌官网为分析广告投放，可使用 target
需要限定广告投放媒体时，使用 platform
需要分析某段历史投放时，合 date_from 和 date_to
若需要覆盖更多广告结果，可提高 depth，但应可能增加的费用

实用场景

监控竞品投放：按 advertiser_ids 持续抓取竞品广告，识别活跃投放时间、创意数量与平台分布。
分析品牌广告：按 target 查询某品牌广告，评估品牌在不同地区和平台的广告覆盖。
追踪广告创意变化：结合 creative_id、first_shown、last_shown，识别广告素材上新、下线与轮换节奏。
筛选特定广告格式：按 format 区分文字、图片、视频广告，制定素材优化与渠道投放策略。
复盘历史广告活动：通过 date_from、date_to 获取时间区间广告数据，用于活动复盘、季节性投放研究与预算分析。

Google Ads 搜索广告实时结果（高级版）

功能说明

计费说明

请求体格式

请求参数

主要参数

附加参数

响应结构

顶层字段

tasks[] 字段

result[] 字段

refinement_chips 字段说明

refinement_chips.items[] 字段

refinement_chips.items[].options[] 字段

ads_search 结果项字段说明

preview_image 字段

请求示例

cURL

Python

TypeScript

响应示例

错误处理

使用建议

实用场景

Google Ads 搜索广告实时结果（高级版） ​

功能说明 ​

计费说明 ​

请求体格式 ​

请求参数 ​

主要参数 ​

附加参数 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

refinement_chips 字段说明 ​

refinement_chips.items[] 字段 ​

refinement_chips.items[].options[] 字段 ​

ads_search 结果项字段说明 ​

preview_image 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

使用建议 ​

实用场景 ​

Google Ads 搜索广告实时结果（高级版）

功能说明

计费说明

请求体格式

请求参数

主要参数

附加参数

响应结构

顶层字段

tasks[] 字段

result[] 字段

refinement_chips 字段说明

refinement_chips.items[] 字段

refinement_chips.items[].options[] 字段

ads_search 结果项字段说明

preview_image 字段

请求示例

cURL

Python

TypeScript

响应示例

错误处理

使用建议

实用场景