获取 Ads Traffic By Keywords 任务结果

接口说明

通过本接口可根据任务 id 获取 Ads Traffic By Keywords 的计算结果，用于查看广告流量预测数据，例如：

• 平均点击成本（CPC）
• 预计点击量（clicks）
• 广告花费（cost）

这类数据通常比常规搜索量更适合评估某个的真实商业需求，因为基于广告流量预测，而不是相似组的广泛匹估算。

注意：自 6 月 1 日起，Ad Traffic By Keywords 返回的是**整个 campaign（任务中提交的）**的批量数据，而不是单个的独立任务结果。

另请注意，Google Ads Keywords Data API 基于新版 Google Ads API。若你仍在使用旧版接口，应升级至 /v3/keywords_data/google_ads/ 路径下的接口体系。

请求方式

GET https://api.seermartech.cn/v3/keywords_data/google_ads/ad_traffic_by_keywords/task_get/$id

说明：

• $id：任务唯一标识，UUID 格式
• 任务结果可在任务创建后的 30 天重复获取

计费说明

该接口本身不重复收费；费用在你创建任务时已经扣除。 任务结果在后续 30 天可拉取。

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

路径参数

字段	类型	说明
id	string	任务唯一标识，UUID 格式，可用于在 30 天随时获取结果

响应结构

接口返回 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	任务 ID，UUID 格式
status_code	integer	任务状态码，通常范围 10000-60000
status_message	string	任务状态说明
time	string	任务执行时间，单位：秒
cost	float	任务成本，单位：USD
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	与创建任务时相同的请求参数
result	array	返回的结果数据

tasks[].result[] 字段

字段	类型	说明
keyword	string	POST 提交时传的；结果会覆盖该任务中提交的所有
location_code	integer	POST 中设置的地区编码；无数据时为 null
language_code	string	POST 中设置的语言编码；无数据时为 null
date_interval	string	POST 中设置的预测时间区间
search_partners	boolean	是否 Google 搜索合作伙伴；该值始终为 false
bid	float	你在创建任务时设置的最高出价，表示愿意为广告支付的价格；设置越高，返回的流量指标和花费通常也越高
match	string	匹类型，可选值：exact、broad、phrase
impressions	float	预计广告展示次数；该字段已废弃，始终为 null
ctr	float	预计点击率；该字段已废弃，始终为 null
average_cpc	float	平均每次点击成本（USD），基于所选时间区间及历史数据估算；无数据时为 null
cost	float	在指定时间区间投放广告的预计花费；无数据时为 null
clicks	float	在指定时间区间预计获得的点击量；无数据时为 null

使用说明

通常流程如下：

1. 通过对应的任务创建接口提交预测任务
2. 获取返回的任务 id
3. 使用本接口按 id 获取结果
4. 如需批量处理已完成任务，也可查询 ready 任务列表，再逐个获取结果

请求示例

cURL

id="02031634-0696-0111-0000-61c2471b87fc"

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

Python

import requests

task_id = "02231934-2604-0066-2000-570459f04879"
url = f"https://api.seermartech.cn/v3/keywords_data/google_ads/ad_traffic_by_keywords/task_get/{task_id}"

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

response = requests.get(url, headers=headers)
result = response.json

# 输出结果
print(result)

TypeScript

import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

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

响应示例

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "ad_traffic_by_keywords",
 "se": "google_ads",
 "id": "06021415-1535-0111-0000-76d1e6dff5bc",
 "language_code": "en",
 "location_code": 2840,
 "bid": 999,
 "match": "exact",
 "keywords": []
 },
 "result": []
 }
 ]
}

状态码与异常处理

• 顶层 status_code 表示整次请求的通用状态
• tasks[].status_code 表示单个任务的执行状态
• 建议同时检查：
• 顶层 status_code 是否为成功
• tasks_error 是否为 0
• tasks[].result 是否为空
• tasks[].status_code 是否返回异常范围状态码

建议在业务系统中建立完善的异常处理机制，例如：

• 任务不存在或已过期
• 任务尚未完成
• 返回结果为空
• 地区、语言或组合无可用数据

结果解读建议

使用该接口时，建议重点以下字段：

• average_cpc：判断商业竞争强度
• clicks：评估潜在广告点击量
• cost：预估投放预算
• match + bid：结合出价与匹方式观察不同投放策略下的数据变化

同时注意：

• impressions 和 ctr 已废弃，不应再作为业务判断依据
• search_partners 始终为 false
• 若返回 null，通常表示该维度暂无可用预测数据

实用场景

• 评估投放价值：对目标获取预计点击量、平均 CPC 和广告花费，快速判断是否值得付费投放。
• 比较商业性：对一组候选词批量查看 CPC 与点击预测，筛选更转化潜力的高价值。
• 制定预算方案：基于不同的预计花费与点击量，测算阶段性广告预算，降低试投成本。
• 优化出价策略：结合 bid 与返回结果，测试不同出价下的流量变化，为竞价模型提供依据。
• ** SEO 优级排序**：用广告流量预测验证真实需求，优布局既有自然流量潜力又有商业价值的主题。