Google Ads 迁移指南

本平台的 Google Ads 数据接口基于最新版本的 Google Ads API 构建，用于替代旧版 Google AdWords API。新版接口提供了更多功能和改进，同时也废弃了部分旧版概念。

如需从旧版 Google AdWords 数据接口迁移至 Google Ads 数据接口，建议按以下步骤执行。

迁移步骤

1. 更新客户端请求路径

如果使用客户端封或自行拼接请求 URL，需要将请求路径中的搜索引擎标识从 google 替换为 google_ads。

例如：

/v3/keywords_data/google/search_volume/task_post/

迁移后：

/v3/keywords_data/google_ads/search_volume/task_post/

该调整适用于 POST、GET 及实时查询请求。

2. 调整 POST 请求参数

除更新请求路径外，部分 POST 请求参数也需要适新版接口。

所有填字段保持不变，但新版接口支持更多功能字段，例如：

• 指定数据统计日期范围；
• 使用 sort_by 对结果排序；
• 获取指定预测周期的广告流量预估数据。

> POST 请求体使用 JSON 数组格式，即使提交一个任务。

[
  {
    "keywords": [
      "running shoes",
      "sports shoes"
    ],
    "location_code": 2840,
    "language_code": "en"
  }
]

3. 检查新增与废弃的响应字段

新版接口为多个端点增加了字段，同时移除了部分旧字段。迁移时请检查依赖旧响应结构的业务逻辑，是 CPC、广告排名、每日流量区间等字段。

4. 测试并迭代

本次迁移不是增量更新。建议在正式切换前执行测试，并根据新版字段约束调整请求参数和结果解析逻辑。

可使用沙箱功能进行调试：

/v3/appendix/sandbox/

主要变化

变化项	说明
更高的数量上限	单个请求可提交的数量由最多 1,000 个提升至最多 20,000 个。
支持日期范围	可指定日期范围，以获取特定周期的数据。
更严格的要求	新版对可提交的有更严格限制，例如不支持 UTF-8 特殊符号的。
支持排序参数	可通过 sort_by 参数对结果进行排序。
新版流量预估	Ad Traffic By Keywords 可返回指定预测周期的预估统计数据。

已废弃的端点

已废弃端点	原因	说明
/v3/keywords_data/google/ad_traffic_by_platforms/task_post/	不再支持平台维度	新版接口提供汇总后的平台数据。
/v3/keywords_data/google/keywords_for_category/task_post/	不再支持分类维度	新版接口没有分类数据的替代能力。
/v3/keywords_data/google/categories/	不再支持分类维度	新版接口没有分类数据的替代能力。

已废弃的请求参数

参数	适用端点	说明
keywords_negative	/v3/keywords_data/google/keywords_for_site/task_post/<br>/v3/keywords_data/google/keywords_for_keywords/task_post/	当前不支持否定。
closely_variants	/v3/keywords_data/google/keywords_for_keywords/task_post/	新版不支持紧密变体。

已废弃的响应参数

参数	适用端点	替代说明
cpc	/v3/keywords_data/google/search_volume/task_get/<br>/v3/keywords_data/google/keywords_for_site/task_post/<br>/v3/keywords_data/google/keywords_for_keywords/task_post/	新版不支持该 CPC 字段。
categories	/v3/keywords_data/google/search_volume/task_get/<br>/v3/keywords_data/google/keywords_for_site/task_post/<br>/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。
daily_impressions_min	/v3/keywords_data/google/ad_traffic_by_keywords/task_get/	支持指定时间段的展示量

实用场景

• 待补充具体业务场景