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

接口说明

该接口用于根据任务 ID 拉取已创建任务的结果，返回一组在不同设备平台上的广告流量预估数据：

• desktop：桌面端
• mobile：移动端
• tablet：平板端

可获取的核心指标：

• 日均展示量预估
• CPC 预估
• 日均点击量预估
• 广告位次预估
• 日均花费预估

注意：

• 本接口所属的 Google AdWords Keywords Data API 为历史版本，现已被 Google Ads API 替代；如有新接需求，建议优使用新版接口。
• 平台 API 返回的预估结果，可能与规划中看到的数据存在差异。这通常与账户历史、广告素材、投放记录等因素。
• 若希望尽量弱化影响因素，可在创建任务时设置较高的 bid。

请求方式

GET /v3/keywords_data/google/ad_traffic_by_platforms/task_get/{id}

完整请求地址示例：

https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_platforms/task_get/{id}

计费说明

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

• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 本次结果查询通常 cost = 0

路径参数

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

返回结构

接口返回 JSON 数据，顶层 tasks 数组，每个任务对象对应一次任务结果。

顶层字段

字段	类型	说明
version	string	当前 API 版本。
status_code	integer	接口通用状态码。建议在程序中做好异常与错误处理。
status_message	string	接口通用状态信息。
time	string	请求执行耗时，单位为秒。
cost	float	本次请求总成本，单位为。结果查询通常为 0。
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	单个任务成本，单位为。
result_count	integer	result 数组中的结果数量。
path	array	请求路径。
data	object	创建任务时传的原始参数。
result	array	结果数组。

data 字段

data 中会返回你在 POST 创建任务时提交的参数，例如：

字段	类型	说明
api	string	API 模块名。
function	string	功能名。
se	string	搜索引擎，固定为 google。
language_code	string	语言代码。
location_code	integer	地区代码。
bid	float	自定义最高出价。
match	string	匹类型。
keywords	array	任务中的列表。
tag	string	自定义标签。

结果字段说明

result[] 中会按设备平台返回结果对象：

• desktop
• mobile
• tablet

三字段结构基本一致。

平台结果通用字段

字段	类型	说明
location_code	integer	POST 请求中设置的地区代码；若无数据则为 null。
language_code	string	POST 请求中设置的语言代码；若无数据则为 null。
bid	float	创建任务时设置的最高自定义出价，即你愿意为广告支付的最高价格。通常出价越高，返回的广告位置和价格也越高。
keyword	string	。对于部分平台返回值，URL 编码会被解码，+ 会被还原为空格。
match	string	匹类型，可选值：exact、broad、phrase。
ad_position_min	float	最低广告位次；无数据则为 null。
ad_position_max	float	最高广告位次；无数据则为 null。
ad_position_average	float	平均广告位次；无数据则为 null。
cpc_min	float	最低历史 CPC，单位；无数据则为 null。
cpc_max	float	最高历史 CPC，单位；无数据则为 null。
cpc_average	float	平均历史 CPC，单位；无数据则为 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	最低日均花费，单位；无数据则为 null。
daily_cost_max	float	最高日均花费，单位；无数据则为 null。
daily_cost_average	float	平均日均花费，单位；无数据则为 null。

认证方式

使用 Bearer Token 认证：

Authorization: Bearer smt_live_YOUR_KEY

请求示例

cURL

id="02031639-0696-0112-0000-21d6ab6aa8f9"

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

Python

import requests

task_id = "02031639-0696-0112-0000-21d6ab6aa8f9"
url = f"https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_platforms/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_platforms/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.6369 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "ad_traffic_by_platforms",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "bid": 999,
 "match": "exact",
 "keywords": [
 "keyword example"
 ],
 "tag": "tag1"
 },
 "result": [
 {
 "desktop": {
 "language_code": "en",
 "location_code": 2840,
 "bid": 999,
 "keyword": "keyword example",
 "match": "exact",
 "ad_position_min": 1.11,
 "ad_position_max": 1,
 "ad_position_average": 1.06,
 "cpc_min": 43.13,
 "cpc_max": 52.72,
 "cpc_average": 47.93,
 "daily_impressions_min": 82.74,
 "daily_impressions_max": 101.13,
 "daily_impressions_average": 91.94,
 "daily_clicks_min": 0.7,
 "daily_clicks_max": 0.86,
 "daily_clicks_average": 0.78,
 "daily_cost_min": 33.69,
 "daily_cost_max": 41.18,
 "daily_cost_average": 37.44
 },
 "mobile": {
 "language_code": "en",
 "location_code": 2840,
 "bid": 999,
 "keyword": "keyword example",
 "match": "exact",
 "ad_position_min": 1.11,
 "ad_position_max": 1,
 "ad_position_average": 1.06,
 "cpc_min": 32.31,
 "cpc_max": 39.49,
 "cpc_average": 35.9,
 "daily_impressions_min": 56.11,
 "daily_impressions_max": 68.58,
 "daily_impressions_average": 62.34,
 "daily_clicks_min": 0.4,
 "daily_clicks_max": 0.49,
 "daily_clicks_average": 0.45,
 "daily_cost_min": 14.44,
 "daily_cost_max": 17.64,
 "daily_cost_average": 16.04
 },
 "tablet": {
 "language_code": "en",
 "location_code": 2840,
 "bid": 999,
 "keyword": "keyword example",
 "match": "exact",
 "ad_position_min": 1.11,
 "ad_position_max": 1,
 "ad_position_average": 1.06,
 "cpc_min": 28.24,
 "cpc_max": 34.51,
 "cpc_average": 31.37,
 "daily_impressions_min": 1.55,
 "daily_impressions_max": 1.9,
 "daily_impressions_average": 1.73,
 "daily_clicks_min": 0.04,
 "daily_clicks_max": 0.04,
 "daily_clicks_average": 0.04,
 "daily_cost_min": 1.12,
 "daily_cost_max": 1.37,
 "daily_cost_average": 1.25
 }
 }
 ]
 }
 ]
}

状态码说明

状态码	说明
20000	请求成功。
10000-60000	任务级状态码范围，含义请结合 status_message 判断。
>= 40000	通常表示任务处理失败或参数/权限等异常。

建议在接时同时处理：

• 顶层 status_code
• tasks[].status_code
• tasks[].result 是否为空

使用建议

1. 通过对应的 POST 接口创建任务。
2. 获取任务 ID 后，使用本接口按 ID 轮询结果。
3. 若任务尚未完成，可稍后重试。
4. 对 desktop、mobile、tablet 的数据分别建模，有助于更精细地制定广告投放策略。
5. 由于 bid 会显著影响预估结果，建议结合不同出价做多组任务对比。

实用场景

• 对比设备投放价值：分别分析桌面端、移动端、平板端的展示、点击与 CPC 差异，帮助广告团队优化预算分。
• 评估商业可投性：基于 daily_clicks_average、cpc_average、daily_cost_average 判断是否适合广告投放池。
• 模拟不同出价结果：为同一设置不同 bid 创建任务，对比广告位次与流量变化，出价策略制定。
• 识别移动优：筛选移动端展示量和点击量明显高于桌面端的，用于移动落地页和移动广告优投放。
• 预估投放成本区间：使用 daily_cost_min/max/average 评估潜在日预算，为广告计划和客户报价提供依据。