创建 Google Ads Search SERP 任务

接口说明

该接口用于创建 Google Ads Search SERP 抓取任务，返回指定广告主在指定地区、平台及时间范围投放的广告信息。数据来源基于 Google Ads Transparency 平台，并由平台 API 进行结构化整理，便于程序化获取和分析。

接口支持按广告主 ID 或目标域名查询，并可结合地区、广告平台、广告格式、时间区间等条件进行过滤。

历史数据最早可追溯至 2018-05-31
支持两种执行优级：普通优级和高优级
任务创建成功后，可通过任务 id 获取结果，也可使用 pingback_url / postback_url 接收异步通知

接口地址

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

计费说明

该接口按任务创建计费。

每个最多 40 条结果的 SERP 单独计费
当 depth 大于 40 时，如果搜索引擎返回 40 条结果，可能产生额外费用
高优级任务（priority=2）会产生额外扣费
参考价约 ¥0.0384 / 次
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求限制

每分钟最多可发送 2000 次 API 调用
每次 POST 请求最多可 100 个任务
如果单次请求中任务数 100，出部分将返回错误 40006
POST 请求体为 JSON 数组格式：[{ ... }]

异步结果获取

任务创建后，可通过以下方式获取结果：

使用返回的唯一任务 ID 轮询结果接口；
设置 pingback_url，任务完成后平台会向该地址发送 GET 请求；
设置 postback_url，任务完成后平台会将结果以 gzip 压缩格式通过 POST 推送到指定地址。

注意事项：

如果回调服务器在 10 秒未响应，连接会因时中断 -时后任务会转 /v3/serp/google/ads_search/tasks_ready/ 列表，可改为主动拉取
pingback_url 和 postback_url 中可使用 $id 和 $tag 占位符，平台在发送请求前会替换为真实值
URL 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23

请求参数

主要参数

字段名	类型	说明
`advertiser_ids`	array	广告主标识数组。当未提供 `target` 时填。最多可传 `25` 个值。可通过广告主查询接口获取可用 `advertiser_ids`。
`target`	string	广告主的域名。当未提供 `advertiser_ids` 时填。
`location_code`	integer	搜索引擎地区代码。可选。若使用该字段，则无需再传 `location_name` 或 `location_coordinate`。示例：`2840`。如未指定 `location_name`、`location_code` 或 `location_coordinate`，则会在所有可用地区范围搜索广告。
`depth`	integer	抓取深度，即返回结果数量。可选。默认值：`40`；最大值：`700`。 `40` 可能触发额外计费。
`priority`	integer	任务优级。可选。`1` = 普通优级（默认）；`2` = 高优级。高优级会额外收费。
`pingback_url`	string	任务完成通知地址。可选。完成后平台会向该地址发送 GET 请求。支持 `$id`、`$tag` 占位符。示例：`https://your-server.com/pingscript?id=$id&tag=$tag`
`postback_url`	string	任务结果推送地址。可选。完成后平台会将结果以 gzip 压缩格式通过 POST 推送。支持 `$id`、`$tag` 占位符。
`postback_data`	string	`postback_url` 的返回数据类型。设置 `postback_url` 时填。可选值：`advanced`

附加参数

字段名	类型	说明
`location_name`	string	搜索引擎地区名。可选。若使用该字段，则无需再传 `location_code` 或 `location_coordinate`。示例：`London,England,United Kingdom`。
`location_coordinate`	string	位置 GPS 坐标。可选。若使用该字段，则无需再传 `location_name` 或 `location_code`。示例：`52.6178549,-155.352142`。
`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`；最大值：当天日期。示例：`2020-01-01`
`date_to`	string	时间区间结束日期。可选。若指定 `date_from`，则该字段填。格式：`yyyy-mm-dd`。最小值：`2018-05-31`；最大值：当天日期。示例：`2020-01-01`

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/google/ads_search/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_code": 2840,
 "platform": "google_search",
 "advertiser_ids": [
 "AR13752565271262920705",
 "AR02439908557932462081"
 ]
 },
 {
 "location_name": "United States",
 "platform": "google_search",
 "advertiser_ids": [
 "AR13752565271262920705",
 "AR02439908557932462081"
 ],
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]'

Python

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"
}

payload = [
 {
 "location_code": 2840,
 "platform": "google_search",
 "advertiser_ids": [
 "AR13752565271262920705",
 "AR02439908557932462081"
 ]
 },
 {
 "location_name": "United States",
 "platform": "google_search",
 "advertiser_ids": [
 "AR13752565271262920705",
 "AR02439908557932462081"
 ],
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

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

TypeScript

import axios from "axios";

const payload = [
 {
 location_code: 2840,
 platform: "google_search",
 advertiser_ids: [
 "AR13752565271262920705",
 "AR02439908557932462081"
 ]
 },
 {
 location_name: "United States",
 platform: "google_search",
 advertiser_ids: [
 "AR13752565271262920705",
 "AR02439908557932462081"
 ],
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
];

axios.post(
 "https://api.seermartech.cn/v3/serp/google/ads_search/task_post",
 payload,
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
 }
).then((response) => {
 // 输出任务创建结果
 console.log(response.data);
}).catch((error) => {
 console.error(error.response?.data || error.message);
});

响应说明

接口返回 JSON 数据，顶层 tasks 数组，用于描述本次提交的任务。

顶层字段

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

tasks 数组中的字段

字段名	类型	说明
`id`	string	平台中的唯一任务 ID，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	任务处理耗时，单位秒
`cost`	float	单个任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	接口路径
`data`	object	与提交时请求参数一致的任务数据
`result`	array \| null	任务创建接口中该字段通常为 `null`，结果需后续获取

建议在生产环境中基于 status_code 和 tasks_error 建立完整的错误处理与重试机制。

响应示例

json

{
 "version": "0.1.20241101",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0746 sec.",
 "cost": 0.0024,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "f2b8c1b0-7f7d-4d9d-9e2d-2d4f5b2c9abc",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.0024,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "google",
 "ads_search",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "google",
 "se_type": "ads_search",
 "priority": 2,
 "depth": 41,
 "location_code": 2840,
 "location_coordinate": "53.476225,-2.243572",
 "platform": "youtube",
 "date_from": "2018-09-30",
 "date_to": "2024-11-12",
 "advertiser_ids": [
 "AR13752565271262920705",
 "AR02439908557932462081"
 ]
 },
 "result": null
 }
 ]
}

状态码与错误处理

常见状态码

状态码	含义
`20000`	请求成功
`20100`	任务已创建
`40006`	单次 POST 请求中的任务数量上限

错误处理建议

当返回 40006 时，请将单次请求任务数控制在 100 个
当使用 postback_url 时，同时提供 postback_data
当使用 date_from / date_to 时，成对传
advertiser_ids 与 target 至少提供一个
若回调服务处理较，建议改用任务 ID 轮询或 /v3/serp/google/ads_search/tasks_ready/ 方式获取结果

实用场景

监控竞品投放：按广告主 ID 持续抓取指定地区的广告投放记录，识别竞品投放节奏、平台偏好和时间分布。
追踪品牌广告历史：按品牌域名和日期区间回溯广告素材历史，评估品牌在不同阶段的推广策略变化。
分析平台分发差异：分别指定 google_search、youtube、google_shopping 等平台，对比同一广告主在不同流量的投放策略。
筛选广告素材类型：结合 format 参数区分文字、图片、视频广告，用于创意分析、素材归档与策略复盘。
构建广告报系统：通过 pingback_url 或 postback_url 接异步处理链路，自动汇总广告监测结果并分析报表。

创建 Google Ads Search SERP 任务 ​

接口说明 ​

接口地址 ​

计费说明 ​

请求限制 ​

异步结果获取 ​

请求参数 ​

主要参数 ​

附加参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应说明 ​

顶层字段 ​

tasks 数组中的字段 ​

响应示例 ​

状态码与错误处理 ​

常见状态码 ​

错误处理建议 ​

实用场景 ​