SeerMarTech API 文档

主题

Google Ads 迁移指南 ​

本指南用于帮助你将旧版 Google AdWords 接口调用迁移到新版 Google Ads 容接口。

新版接口基于最新的 Google Ads 程序化能力构建，相比旧版接口提供了更高的请求上限、日期区间支持、排序能力以及更新的流量预估逻辑；同时，部分旧概念、字段和端点已被废弃。 如果你当前仍在使用 /v3/keywords_data/google/... 路径下的旧版广告数据接口，建议尽快迁移到 /v3/keywords_data/google_ads/... 对应路径。

迁移前准备 ​

迁移过程建议按以下 4 步执行：

1. 调整客户端请求路径 ​

如果你的程序当前使用旧版 google 路径，需要将请求 URL 中的搜索引擎标识从 google 替换为 google_ads。

例如：

  • 旧路径：/v3/keywords_data/google/search_volume/live/
  • 新路径：/v3/keywords_data/google_ads/search_volume/live/

这项调整适用于 POST 与 GET 请求。

2. 更新 POST 请求参数 ​

除了 URL 路径变化外，你还需要检查 POST 请求体中的参数。 虽然核心填字段整体保持一致，但新版接口引了若干新能力，同时也移除了部分旧参数。

注意：本平台 POST 请求体统一为 JSON 数组格式：

json
[
 {
 "keywords": ["keyword example"],
 "location_code": 2840,
 "language_code": "en"
 }
]

3. 检查新增字段与废弃字段 ​

新版接口在多个端点中增加了新的响应字段，同时也移除了旧版中的部分字段。 如果你的业务代码依赖旧字段做解析、库或报表计算，需要重点检查。

4. 测试并迭代 ​

这不是一次简单的小版本升级，迁移后建议：

  • 逐个端点验证返回结构
  • 校验是否满足新规则
  • 重新确认排序、过滤与日期区间参数
  • 比对新旧结果差异并调整业务逻辑

如需联调验证，可使用沙箱能力进行测试：

  • /v3/appendix/sandbox/

主要变化 ​

变化项说明
更高的请求上限单次请求可获取的数量由 1,000 提升至 20,000
支持日期区间可指定时间范围，获取某一时间段的数据
规则更严格新版对可提交有更严格限制，例如不支持 UTF-8 特殊符号的
支持排序参数现在可以使用 sort_by 对结果进行排序
流量预估逻辑更新“按广告流量预估”返回指定预测时间段的统计数据

已废弃端点 ​

以下旧端点不再建议使用，且新版接口中没有等价的替代能力或底层平台不再支持对应概念。

端点废弃原因说明
/v3/keywords_data/google/ad_traffic_by_platforms/task_post/不再支持平台维度新版提供聚合后的平台数据
/v3/keywords_data/google/keywords_for_category/task_post/不再支持分类目录新版无 category 对应替代接口
/v3/keywords_data/google/categories/不再支持分类目录新版无 category 对应替代接口

已废弃请求参数 ​

以下请求参数在新版中已不再支持：

参数适用旧端点说明
keywords_negative/v3/keywords_data/google/keywords_for_site/task_post/、/v3/keywords_data/google/keywords_for_keywords/task_post/当前不支持否定
closely_variants/v3/keywords_data/google/keywords_for_keywords/task_post/新版不支持 closely variants

已废弃响应字段 ​

以下字段在新版返回结果中已废弃或被替代：

字段适用旧端点说明
cpc/v3/keywords_data/google/search_volume/task_get/、/v3/keywords_data/google/keywords_for_site/task_post/、/v3/keywords_data/google/keywords_for_keywords/task_post/新版不再提供该字段
categories/v3/keywords_data/google/search_volume/task_get/、/v3/keywords_data/google/keywords_for_site/task_post/、/v3/keywords_data/google/keywords_for_keywords/task_post/新版不再支持分类目录数据
ad_position_min/v3/keywords_data/google/ad_traffic_by_keywords/task_get/广告位次概念已废弃
ad_position_max/v3/keywords_data/google/ad_traffic_by_keywords/task_get/广告位次概念已废弃
ad_position_average/v3/keywords_data/google/ad_traffic_by_keywords/task_get/广告位次概念已废弃
cpc_min/v3/keywords_data/google/ad_traffic_by_keywords/task_get/支持历史平均 CPC
cpc_max/v3/keywords_data/google/ad_traffic_by_keywords/task_get/支持历史平均 CPC
cpc_average/v3/keywords_data/google/ad_traffic_by_keywords/task_get/由 average_cpc 表示历史平均 CPC
daily_impressions_min/v3/keywords_data/google/ad_traffic_by_keywords/task_get/支持指定时间段的 impressions
daily_impressions_max/v3/keywords_data/google/ad_traffic_by_keywords/task_get/支持指定时间段的 impressions
daily_impressions_average/v3/keywords_data/google/ad_traffic_by_keywords/task_get/支持指定时间段的 impressions
daily_clicks_min/v3/keywords_data/google/ad_traffic_by_keywords/task_get/支持指定时间段的 clicks
daily_clicks_max/v3/keywords_data/google/ad_traffic_by_keywords/task_get/支持指定时间段的 clicks
daily_clicks_average/v3/keywords_data/google/ad_traffic_by_keywords/task_get/支持指定时间段的 clicks
daily_cost_min/v3/keywords_data/google/ad_traffic_by_keywords/task_get/指定时间段的花费由 cost_micros 表示
daily_cost_max/v3/keywords_data/google/ad_traffic_by_keywords/task_get/指定时间段的花费由 cost_micros 表示
daily_cost_average/v3/keywords_data/google/ad_traffic_by_keywords/task_get/指定时间段的花费由 cost_micros 表示

旧版与新版接口路径对 ​

以下为常用旧版 AdWords 风格接口与新版 Ads 风格接口的对应。

Search Volume ​

旧版路径新版路径
/v3/keywords_data/google/search_volume/live//v3/keywords_data/google_ads/search_volume/live/
/v3/keywords_data/google/search_volume/task_post//v3/keywords_data/google_ads/search_volume/task_post/
/v3/keywords_data/google/search_volume/tasks_ready//v3/keywords_data/google_ads/search_volume/tasks_ready/
/v3/keywords_data/google/search_volume/task_get//v3/keywords_data/google_ads/search_volume/task_get/

Keywords For Keywords ​

旧版路径新版路径
/v3/keywords_data/google/keywords_for_keywords/live//v3/keywords_data/google_ads/keywords_for_keywords/live/
/v3/keywords_data/google/keywords_for_keywords/task_post//v3/keywords_data/google_ads/keywords_for_keywords/task_post/
/v3/keywords_data/google/keywords_for_keywords/tasks_ready//v3/keywords_data/google_ads/keywords_for_keywords/tasks_ready/
/v3/keywords_data/google/keywords_for_keywords/task_get//v3/keywords_data/google_ads/keywords_for_keywords/task_get/

Keywords For Site ​

旧版路径新版路径
/v3/keywords_data/google/keywords_for_site/live//v3/keywords_data/google_ads/keywords_for_site/live/
/v3/keywords_data/google/keywords_for_site/task_post//v3/keywords_data/google_ads/keywords_for_site/task_post/
/v3/keywords_data/google/keywords_for_site/tasks_ready//v3/keywords_data/google_ads/keywords_for_site/tasks_ready/
/v3/keywords_data/google/keywords_for_site/task_get//v3/keywords_data/google_ads/keywords_for_site/task_get/

Ad Traffic By Keywords ​

旧版路径新版路径
/v3/keywords_data/google/ad_traffic_by_keywords/live//v3/keywords_data/google_ads/ad_traffic_by_keywords/live/
/v3/keywords_data/google/ad_traffic_by_keywords/task_post//v3/keywords_data/google_ads/ad_traffic_by_keywords/task_post/
/v3/keywords_data/google/ad_traffic_by_keywords/tasks_ready//v3/keywords_data/google_ads/ad_traffic_by_keywords/tasks_ready/
/v3/keywords_data/google/ad_traffic_by_keywords/task_get//v3/keywords_data/google_ads/ad_traffic_by_keywords/task_get/

迁移示例 ​

下面示例演示如何将旧版 Search Volume 调用切换到新版 Google Ads 路径。

cURL ​

bash
curl --request POST "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/live/" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data '[
 {
 "keywords": ["tesla", "electric car"],
 "location_code": 2840,
 "language_code": "en"
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/live/"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "keywords": ["tesla", "electric car"],
 "location_code": 2840,
 "language_code": "en"
 }
]

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

TypeScript ​

typescript
const url = "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/live/";

const payload = [
 {
 keywords: ["tesla", "electric car"],
 location_code: 2840,
 language_code: "en",
 },
];

async function main {
 const response = await fetch(url, {
 method: "POST",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 body: JSON.stringify(payload),
 });

 const data = await response.json;
 console.log(data);
}

main;

迁移检查单 ​

建议你在迁移时逐项核对：

  • 将所有 /v3/keywords_data/google/... 请求路径替换为 /v3/keywords_data/google_ads/...
  • 检查是否仍在使用废弃端点
  • 删除不再支持的请求参数，如 keywords_negative、closely_variants
  • 更新响应解析逻辑，移除对废弃字段的依赖
  • 验证是否符合新版要求
  • 如涉及广告流量预测，重新适日期区间和成本字段
  • 在测试环境或沙箱中完成回归验证后再上线

注意事项 ​

为旧版 Google AdWords 能力退场后影响你的系统稳定性，建议尽快完成整体迁移。 如果你的业务仍基于旧版路径进行请求，后续可能出现容性问题、字段缺失或结果不一致等。

实用场景 ​

  • 迁移旧版链：将已有的搜索量、拓展和站点挖词程序从旧路径平滑切换到新版路径，降低历史系统停摆风险。
  • 升级广告预估模型：利用新版按时间段返回的流量与花费数据，重建更接近投放周期的预算预测模型。
  • 批量扩展规模：借助更高的单次请求上限，一次性处理更多，提升大规模行业词库建设效率。
  • 优化报表字段映射：根据废弃字段与替代字段，更新 BI、数据仓库和监控报表，迁移后统计口径失真。
  • 重构投放前分析流程：结合排序、日期区间和新版限制，重新设计投放前的筛选逻辑，提高选词准确性。

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

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