按任务 ID 获取 Google 广告流量预估结果

接口说明

用于根据任务 ID 获取 Google 广告流量预估 的执行结果。

该接口返回指定的广告流量估算数据：

• 每日展示量预估
• 平均点击价格（CPC）预估
• 每日点击量预估
• 每日花费预估
• 广告排名区间与均值

这些数据通常比常规搜索量更适合评估某个的真实商业需求，因为常规搜索量往往基于一组相似的广泛匹估算，而本接口更聚焦于广告投放场景下的流量与成本表现。

注意：

• 该组接口属于较早版本的数据能力，当前已逐步由新版 Google Ads 接口替代。
• 返回结果可能与广告平台规划中看到的数据存在差异，因为平台平台会结合账户历史、创意素材、账户表现等因素生成估算结果。
• 为尽量降低因素影响，创建任务时可设置较高的 bid。

请求方式

GET /v3/keywords_data/google/ad_traffic_by_keywords/task_get/$id

请求参数

字段	类型	说明
id	string	任务唯一标识符，UUID 格式。任务创建后可在 30 天 随时通过该 ID 获取结果。

计费说明

该接口本身为 结果查询接口，账户在 创建任务时 扣费；任务结果在后续 30 天可获取。

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

响应结构

接口返回 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	任务状态码，通常范围为 10000-60000
status_message	string	任务状态信息
time	string	当前任务处理耗时，单位秒
cost	float	当前任务成本，单位 USD
result_count	integer	result 数组中的结果条数
path	array	请求路径
data	object	与创建任务时提交的参数一致
result	array	结果数据数组

tasks[].result[] 字段

字段	类型	说明
location_code	integer	POST 请求中指定的地区编码；如无数据则为 null
language_code	string	POST 请求中指定的语言编码；如无数据则为 null
bid	float	创建任务时设置的最高出价，表示你愿意为广告支付的最高价格。出价越高，返回的广告位置和价格通常越高
keyword	string	请求中的
match	string	匹类型，可选值：exact、broad、phrase
ad_position_min	float	广告最低排名；无数据时为 null
ad_position_max	float	广告最高排名；无数据时为 null
ad_position_average	float	广告平均排名；无数据时为 null
cpc_min	float	历史最低点击单价（USD）；无数据时为 null
cpc_max	float	历史最高点击单价（USD）；无数据时为 null
cpc_average	float	历史平均点击单价（USD）；无数据时为 null
daily_impressions_min	float	每日最低展示量预估；无数据时为 null
daily_impressions_max	float	每日最高展示量预估；无数据时为 null
daily_impressions_average	float	每日平均展示量预估；无数据时为 null
daily_clicks_min	float	每日最低点击量预估；无数据时为 null
daily_clicks_max	float	每日最高点击量预估；无数据时为 null
daily_clicks_average	float	每日平均点击量预估；无数据时为 null
daily_cost_min	float	每日最低花费预估（USD）；无数据时为 null
daily_cost_max	float	每日最高花费预估（USD）；无数据时为 null
daily_cost_average	float	每日平均花费预估（USD）；无数据时为 null

调用示例

cURL

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

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

Python

import requests

task_id = "02031634-0696-0111-0000-61c2471b87fc"
url = f"https://api.seermartech.cn/v3/keywords_data/google/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)
print(response.status_code)
print(response.json)

TypeScript

import axios from "axios";

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

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/keywords_data/google/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": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.5868 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "ad_traffic_by_keywords",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "bid": 999,
 "match": "exact",
 "keywords": [],
 "tag": "tag1"
 },
 "result": []
 }
 ]
}

状态码说明

状态码	说明
20000	请求成功
10000-60000	任务级状态码范围，表示任务处理状态或错误信息

完整错误码与状态说明请参考 /v3/appendix/errors。

使用建议

• 若返回结果与预期差异较大，优检查创建任务时的 bid 是否过低。
• 若 result 为空，通常表示任务尚未完成、无可用数据，或尚未返回该的广告流量估算。
• cpc_*、daily_cost_* 字段均为 USD 单位，如需在业务系统中展示人民币，可自行按汇率换算。
• 建议结合 match 类型一起分析，因为 exact、phrase、broad 会直接影响流量与成本估算结果。

实用场景

• 评估商业价值：根据展示量、点击量与 CPC 预估判断某个是否备投放和转化潜力。
• 测算广告预算区间：结合 daily_cost_min/max/average 预估不同的日预算需求，投放规划。
• 筛选高意图：通过点击量与平均 CPC 识别竞争较高、商业意图更强的搜索词。
• 比较匹方式差异：对同一分别分析 exact、phrase、broad 的流量与成本变化，优化投放策略。
• ** SEO 选词优级排序**：将广告流量预估与自然搜索数据结合，优布局备真实商业需求的。