SeerMarTech API 文档

主题

获取 Google Ads Search Advanced 结果（按任务 ID） ​

通过本接口可根据任务 ID 获取 Google Ads Search Advanced 的采集结果。

接口说明 ​

  • 请求方式：GET
  • 请求地址：https://api.seermartech.cn/v3/serp/google/ads_search/task_get/advanced/$id

计费说明 ​

该接口本身不会重复扣费。费用在创建任务时产生；任务结果在随后 30 天可获取。

如平台单任务有报价，请按人民币换算理解；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数 ​

字段类型说明
idstring任务唯一标识，UUID 格式。可在任务创建后的 30 天随时用于获取结果。

返回结果结构 ​

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

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用状态码。完整错误码请参考文档中的错误码附录。建议在接时做好异常与错误处理。
status_messagestring通用状态信息。
timestring执行耗时，单位秒。
costfloat本次请求总费用，单位 USD。获取已存在任务结果通常为 0。
tasks_countintegertasks 数组中的任务数量。
tasks_errorinteger返回错误的任务数。
tasksarray任务数组。

tasks 数组字段 ​

字段类型说明
idstring任务 ID，UUID 格式。
status_codeinteger任务状态码，范围通常为 10000-60000。
status_messagestring任务状态说明。
timestring任务执行耗时，单位秒。
costfloat该任务费用，单位 USD。
result_countintegerresult 数组中的结果数。
patharray请求路径。
dataobject与创建任务时传的参数一致。
resultarray结果数组。

result 数组字段 ​

字段类型说明
keywordstring创建任务时的。返回时会对 %## 进行解码，+ 会被解码为空格。
typestringPOST 提交时指定的搜索引擎类型。
se_domainstringPOST 提交时指定的搜索引擎域名。
location_codeintegerPOST 提交时指定的位置编码。
language_codestringPOST 提交时指定的语言编码。
check_urlstring搜索结果直达链接；本接口中该字段为 null。
datetimestring结果获取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
spellobject搜索引擎自动纠错信息；若无纠错则为 null。
refinement_chipsobject搜索细化推荐项。
item_typesarray当前 SERP 中返回的结果类型列表。该接口可能：ads_search。
se_results_countintegerSERP 总结果数。
items_countintegeritems 数组中的结果数量。
itemsarray实返回的搜索结果。

refinement_chips 字段说明 ​

refinement_chips ​

字段类型说明
typestring素类型，固定为 refinement_chips。
xpathstring素的 XPath。
itemsarray细化选项列表。

refinement_chips.items[] ​

字段类型说明
typestring素类型，固定为 refinement_chips_element。
titlestring选项标题。
urlstring带细化参数的搜索 URL。
domainstringSERP 中显示的域名。
optionsarray更进一步的细化选项。

refinement_chips.items[].options[] ​

字段类型说明
typestring素类型，固定为 refinement_chips_option。
titlestring选项标题。
urlstring带细化参数的搜索 URL。
domainstringSERP 中显示的域名。

items[] 中 ads_search 类型字段说明 ​

字段类型说明
typestring素类型，固定为 ads_search。
rank_groupinteger同类型组排名。只在相同 type 之间计数。
rank_absoluteinteger在整个 SERP 中的绝对排名。
advertiser_idstring广告主账户唯一标识。
creative_idstring广告创意唯一标识。
titlestring素标题，通常为广告主名称。
urlstring广告链接，指向 Ads Transparency 平台中的广告。
verifiedboolean广告主是否已验证；若为 true 表示已通过 Google Ads 验证。
formatstring广告格式，可选值：text、image、video。
preview_imagearray广告预览图信息。
preview_urlstring广告预览页链接。
first_shownstring广告首次展示时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
last_shownstring广告最近一次展示时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。

preview_image[] ​

字段类型说明
urlstring预览图地址。
heightinteger预览图高度。
widthinteger预览图宽度。

Sandbox ​

如需查看该接口可能返回的完整字段结构，可请求 Sandbox 地址：

https://sandbox.本平台.com/v3/serp/google/ads_search/task_get/advanced/00000000-0000-0000-0000-000000000000

Sandbox 会返回带有模拟数据的完整字段集合，不会产生费用。

请求示例 ​

cURL ​

bash
id="02261816-2027-0066-0000-c27d02864073"

curl --location --request GET "https://api.seermartech.cn/v3/serp/google/ads_search/task_get/advanced/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python ​

python
import requests

task_id = "02231256-2604-0066-2000-57133b8fc54e"

url = f"https://api.seermartech.cn/v3/serp/google/ads_search/task_get/advanced/{task_id}"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const taskId = "02231256-2604-0066-2000-57133b8fc54e";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/google/ads_search/task_get/advanced/${taskId}`,
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
}).then((response) => {
 // 返回任务结果
 console.log(response.data);
}).catch((error) => {
 console.error(error);
});

结合 tasks_ready 获取已完成任务 ​

通常建议通过 /v3/serp/google/ads_search/tasks_ready 获取已完成任务，再使用对应任务 ID 拉取 Advanced 结果。

Python 示例 ​

python
import requests

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

# 1. 获取已完成任务列表
ready_resp = requests.get(
 "https://api.seermartech.cn/v3/serp/google/ads_search/tasks_ready",
 headers=headers
)
ready_data = ready_resp.json

results = []

if ready_data.get("status_code") == 20000:
 for task_group in ready_data.get("tasks", []):
 for task_info in task_group.get("result", []):
 task_id = task_info.get("id")
 if not task_id:
 continue

 # 2. 根据任务 ID 获取 Advanced 结果
 resp = requests.get(
 f"https://api.seermartech.cn/v3/serp/google/ads_search/task_get/advanced/{task_id}",
 headers=headers
 )
 results.append(resp.json)

print(results)

响应示例 ​

json
{
 "version": "0.1.20241101",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0338 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "google",
 "se_type": "ads_search",
 "location_code": 2840,
 "platform": "google_search",
 "advertiser_ids": [],
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 0,
 "items_count": 40,
 "items": []
 }
 ]
 }
 ]
}

状态码说明 ​

  • 20000：请求成功
  • 任务级错误码通常位于 10000-60000
  • 若 tasks_error > 0，说明部分任务返回异常
  • 建议同时检查：
  • 顶层 status_code
  • tasks[].status_code
  • tasks[].result 是否为空

使用建议 ​

  1. 提交 SERP 采集任务；
  2. 通过 /v3/serp/google/ads_search/tasks_ready 查询哪些任务已完成；
  3. 使用本接口按任务 ID 获取详细结果；
  4. 对 items 中的 ads_search素进行结构化解析，提取广告主、创意、展示时间、广告格式等信息。

实用场景 ​

  • 监控竞品广告主投放：按拉取广告主列表、创意 ID 与展示时间，识别竞品是否持续投放及投放周期变化。
  • 分析广告样式分布：统计 format 字段中的文本、图片、视频广告占比，为品牌投放素材策略提供依据。
  • 追踪广告首次与最近展示时间：结合 first_shown 和 last_shown 判断广告生命周期，评估竞品活动是否为短期促销或长期常驻。
  • 识别已验证广告主：利用 verified 字段筛选官方认证账户，品牌分析与行业头部广告主识别。
  • 挖掘搜索细化方向：解析 refinement_chips 中的推荐选项，发现用户在广告搜索场景下的进一步意图分支。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API