数据 / Google Ads / Ad Traffic By Keywords / Live

接口说明

/v3/keywords_data/google_ads/ad_traffic_by_keywords/live 用于按获取广告流量预估数据，可返回用于估算广告展示量、平均点击成本、点击量和投放成本的一组指标。

相较于普通搜索量数据，这个接口更适合评估某个的真实商业需求，因为它基于广告投放预测，而不是相近集合的宽泛匹搜索量估算。

注意：

• 自 6 月 1 日起，该接口返回的是**整个广告活动（本次任务中提交的）**的批量数据。
• 该能力基于平台广告 API 的最新版本；如果你仍在使用旧版广告接口，建议迁移到当前 Google Ads 容路径。
• 每个账号每分钟最多调用 12 次 Google Ads Live 类端点。
• Google Ads 返回结果会受账号历史、已有创意、账户状态等因素影响。为了尽量减少这些因素对预测值的干扰，建议设置较高的 bid。
• 若未指定预测时间范围，默认使用 next_month。

请求地址

POST https://api.seermartech.cn/v3/keywords_data/google_ads/ad_traffic_by_keywords/live

计费说明

该接口按请求计费，无论 keywords 数组中 1 个还是 1000 个，单次请求价格相同。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

时间范围说明

你可以通过以下两种方式指定预测时间段：

1. 使用 date_from 和 date_to 指定未来的精确日期范围；
2. 使用 date_interval 指定预设区间：next_week、next_month、next_quarter

如果两种方式都不传，默认采用：

• date_interval: next_month

请求限制

• 单个 keywords 数组最多支持 1000 个
• 每个最长 80 个字符
• 每个短语最多 10 个单词
• 系统会将统一转为小写
• POST 请求体是 JSON 数组：[{ ... }]
• 账号整体 API 吞吐最高可达每分钟 2000 次调用，但本接口所属 Google Ads Live 端点仍受 每分钟 12 次 的专有限制约束

请求参数

以下为设置任务时可用的字段。

字段名	类型	填	说明
keywords	array	是	列表。最多 1000 个；每个最长 80 字符、最多 10 个单词。会被转为小写。部分组合可能返回无数据。Google Ads 不支持某些符号或字符（如部分 UTF 符号、emoji），提交时不可使用。
bid	integer	是	自定义最高出价。返回的预估数据基于该值计算。通常 bid 越高，返回的指标值也越高。
match	string	是	匹类型，可选值：exact、broad、phrase
location_name	string	否	搜索引擎地区名。不传则返回范围结果。使用该字段时，无需传 location_code 或 location_coordinate。示例：London,England,United Kingdom
location_code	integer	否	搜索引擎地区代码。不传则返回范围结果。使用该字段时，无需传 location_name 或 location_coordinate。示例：2840
location_coordinate	string	否	地理坐标，格式为 "latitude,longitude"。使用该字段时，无需传 location_name 或 location_code。返回数据按该坐标所属国家提供。示例：52.6178549,-155.352142
language_name	string	否	搜索引擎语言名。示例：English
language_code	string	否	搜索引擎语言代码。示例：en
date_from	string	条件填	预测时间范围开始日期。若传 date_to，则传该字段。格式：yyyy-mm-dd。最小值通常为明天。若同时传 date_from 和 date_to，则无需传 date_interval。
date_to	string	条件填	预测时间范围结束日期。若传 date_from，则传该字段。格式：yyyy-mm-dd。最小值为 date_from + 1 天，最大值为下一年当月当日。若同时传 date_from 和 date_to，则无需传 date_interval。
date_interval	string	否	预测时间区间。可选值：next_week、next_month、next_quarter。默认值：next_month。传该字段时，无需传 date_from 和 date_to。
sort_by	string	否	结果按降序排序，可选值：relevance、impressions、ctr、average_cpc、cost、clicks。默认值：relevance
tag	string	否	自定义任务标识，最长 255 字符。可用于请求与结果的追踪，响应中的 data 对象会返回该值。

地区与语言列表

可通过以下接口获取可用地区和语言：

• 地区：/v3/keywords_data/google_ads/locations
• 语言：/v3/keywords_data/google_ads/languages

日期字段补说明

date_from 的可用范围与状态接口中 actual_data 字段：

• 若 /v3/keywords_data/google_ads/status/ 返回 actual_data = false，则 date_from 可设置为上上月及更早
• 若 /v3/keywords_data/google_ads/status/ 返回 actual_data = true，则 date_from 可设置为上月及更早

返回结果说明

接口返回 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	任务唯一标识，UUID 格式
status_code	integer	任务状态码
status_message	string	任务状态信息
time	string	任务执行耗时
cost	float	任务费用，单位 USD
result_count	integer	result 数组数量
path	array	请求路径
data	object	与请求中提交参数一致的数据对象
result	array	结果数组

result 数组字段

字段名	类型	说明
keyword	string	请求中的
location_code	integer	请求中的地区代码；无数据时为 null
language_code	string	请求中的语言代码；无数据时为 null
date_interval	string	请求中的预测时间区间
search_partners	boolean	是否搜索合作伙伴。该字段已废弃，固定为 false
bid	integer	请求中的最高出价
match	string	匹类型：exact、broad、phrase
impressions	float	预估广告展示量。该字段已废弃，固定为 null
ctr	float	预估点击率。该字段已废弃，固定为 null
average_cpc	float	平均每次点击成本（USD）；无数据时为 null
cost	float	在指定时间范围的广告预计花费；无数据时为 null
clicks	float	在指定时间范围的预估点击量；无数据时为 null

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google_ads/ad_traffic_by_keywords/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "language_name": "English",
 "bid": 999,
 "match": "exact",
 "keywords": [
 "seo marketing"
 ]
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_ads/ad_traffic_by_keywords/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "location_name": "United States",
 "language_name": "English",
 "bid": 999,
 "match": "exact",
 "keywords": [
 "seo marketing"
 ]
 }
]

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

TypeScript

import axios from "axios";

const payload = [
 {
 location_name: "United States",
 language_name: "English",
 bid: 999,
 match: "exact",
 keywords: ["seo marketing"]
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google_ads/ad_traffic_by_keywords/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: payload
})
 .then((response) => {
 // 输出接口返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

响应示例

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.5834 sec.",
 "cost": 0.075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "ad_traffic_by_keywords",
 "se": "google_ads",
 "language_code": "en",
 "location_code": 2840,
 "bid": 999,
 "match": "exact",
 "keywords": [
 "seo marketing"
 ]
 },
 "result": []
 }
 ]
}

状态码与错误处理

请根据返回中的 status_code 和 status_message 实现异常处理机制，注意以下两层状态：

• 顶层响应状态：表示整个请求是否成功
• tasks任务状态：表示某个任务是否成功

常见处理建议：

1. 检查顶层 status_code 是否成功；
2. 再逐个检查 tasks[].status_code；
3. 对于 result 为空、字段为 null 的，按“无可用广告预测数据”处理，而不是直接判定为接口失败；
4. 针对 Google Ads Live 接口的频率限制，建议在应用层实现节流与重试机制。

使用建议

• 如果希望不同之间的预测结果更可比性，可统一使用相同的 bid、地区和语言；
• 若某些始终返回空数据，通常与平台广告系统的覆盖范围、字符限制或组合方式；
• 由于该接口现按整批返回活动级批量结果，建议在一组任务中放同一主题、同一地区、同一语言下的，便于分析与投放估算；
• 如果业务更未来投放计划，优使用 date_interval；如果要贴合活动排期，则使用 date_from + date_to。

实用场景

• 评估投放价值：候选及出价，快速估算点击量、平均 CPC 和成本，判断某个词是否值得投放。
• 筛选高商业意图：对一批 SEO 或 SEM 候选词做广告流量预测，识别更可能带来真实点击和转化的。
• 制定预算方案：基于不同时间区间和出价设置，预测未来一周、一个月或一个季度的广告花费，提升预算分准确性。
• 比较匹类型效果：分别测试 exact、phrase、broad 三种匹方式，分析不同投放策略下的点击与成本差异。
• 校准搜索量判断：将广告流量预测数据与常规搜索量数据结合，凭广泛匹搜索量高估真实需求。