创建 Google Ads Advertisers SERP 任务

本接口用于创建 Google Ads Advertisers SERP 查询任务。该数据基于 Google Ads Transparency 平台，可返回指定在特定地区下对应的广告主信息。

接口支持按任务异步执行。创建任务后，您可以通过任务 id 轮询获取结果；也可以在创建任务时设置 pingback_url 或 postback_url，由本平台在任务完成后主动通知或推送结果。

接口地址

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

计费说明

创建任务时即产生扣费对任务创建计费。

参考价约 ¥0.0096 / 次如使用高优级任务，费用会额外增加。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

请求方法：POST
请求体格式：JSON 数组 [{ ... }]
编码：UTF-8
单次 POST 最多可提交 100 个任务
接口频率上限：每分钟最多 2000 次 API 调用
若单次请求中任务数 100，出部分会返回错误 40006

任务结果获取方式

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

使用返回的任务 id 查询已完成任务结果；
设置 pingback_url，任务完成后本平台向该地址发送 GET 通知；
设置 postback_url，任务完成后本平台向该地址发送压缩为 gzip 的 POST 结果数据。

如果您的回调服务器在 10 秒未响应，本平台会终止连接，任务将转 /v3/serp/google/ads_advertisers/tasks_ready/ 列表，供后续主动拉取。

主要请求参数

字段名	类型	填	说明
`keyword`	string	是	查询，最长 700 个字符。`%##` 会被解码，字符 `+` 会被解码为空格。如需传字面量 `%`，请使用 `%25`；如需传字面量 `+`，请使用 `%2B`。
`priority`	integer	否	任务优级。`1` = 普通优级（默认）；`2` = 高优级。高优级执行更快，但费用更高。
`location_code`	integer	否	搜索地区编码。设置后无需再传 `location_name` 或 `location_coordinate`。示例：`2840`。可通过 `/v3/serp/google/ads_advertisers/locations` 获取可用地区列表。若未传任一地区参数，则会在所有可用地区范围搜索广告主。
`pingback_url`	string	否	任务完成后的通知地址。本平台会向该地址发送 GET 请求。支持使用 `$id` 和 `$tag` 占位符，发送前会替换为真实值。示例：`https://your-server.com/pingscript?id=$id&tag=$tag`。特殊字符会自动 URL 编码，如 `#` 会编码为 `%23`。
`postback_url`	string	否	任务完成后的结果推送地址。本平台会向该地址发送结果的 POST 请求，数据为 `gzip` 压缩格式。支持 `$id` 和 `$tag` 占位符。特殊字符会自动 URL 编码。
`postback_data`	string	条件填	当设置了 `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` 对象中会返回该值。

响应结构

接口返回 JSON 数据， tasks 数组记录本次提交的任务信息。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码，完整列表见 `/v3/appendix/errors`
`status_message`	string	通用状态信息
`time`	string	请求执行时间，单位秒
`cost`	float	本次请求总费用，单位 USD
`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
`result_count`	integer	`result` 数组数量
`path`	array	请求路径
`data`	object	与提交时请求参数对应的数据对象
`result`	array / null	结果数组。对于创建任务接口，此处通常为 `null`

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/google/ads_advertisers/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_code": 2840,
 "keyword": "apple"
 },
 {
 "location_name": "United States",
 "keyword": "apple",
 "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_advertisers/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 "location_code": 2840,
 "keyword": "apple"
 },
 {
 "location_name": "United States",
 "keyword": "apple",
 "priority": 2,
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

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

TypeScript

typescript

import axios from "axios";

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

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/google/ads_advertisers/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: payload
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

json

{
 "version": "0.1.20241101",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0630 sec.",
 "cost": 0.0006,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "12345678-1234-1234-1234-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0000 sec.",
 "cost": 0.0006,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "google",
 "ads_advertisers",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "google",
 "se_type": "ads_advertisers",
 "location_code": 2840,
 "keyword": "apple",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码说明

状态码	说明
`20000`	请求成功
`20100`	任务创建成功
`40006`	单次 POST 中任务数量 100 个
状态码	请参考 `/v3/appendix/errors`

建议在接时完善异常处理逻辑，是任务级别状态码与回调时场景。

使用建议

优使用 location_code，便于稳定匹地区；
如需系统异步处理，建议 pingback_url 或 postback_url；
大批量提交时，请将每次请求控制在 100 个任务；
若使用 postback_url，请确保服务端支持接收 gzip 压缩请求体；
对中的 %、+ 等特殊字符做好编码处理。

实用场景

监控品牌投放：按品牌词定期创建任务，识别哪些广告主在目标地区持续投放，竞品广告监测。
对比地区广告差异：针对同一设置多个地区任务，分析不同市场中的广告主分布，支持区域化投放研究。
识别竞品抢词行为：围绕核心商业追踪广告主变化，及时发现竞品对品牌词或品类词的抢占。
构建广告主报库：批量提交行业，沉淀广告主出现频次与地区覆盖数据，支持销售、市场和 SEO 团队分析。
触发自动化预警：结合 pingback_url 或 postback_url，在发现新广告主某市场时自动通知业务系统。

创建 Google Ads Advertisers SERP 任务 ​

接口地址 ​

计费说明 ​

请求说明 ​

任务结果获取方式 ​

主要请求参数 ​

附加请求参数 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码说明 ​

使用建议 ​

实用场景 ​