Google 广告流量按设备拆分（实时）

接口说明

该接口用于针对一组，获取广告流量在不同设备平台上的估算数据，支持以下平台：

• 桌面端（desktop）
• 移动端（mobile）
• 平板端（tablet）

返回结果各平台的广告、点击、CPC 以及广告位估算值。

与 /v3/keywords_data/google/ad_traffic_by_keywords/live/ 不同，本接口返回的是整组的汇总结果，而不是逐个分别返回独立结果。

如果你的系统需要实时返回结果，建议使用当前 Live 方法。与标准任务模式不同，Live 方法无需分开发起 POST 和 GET 请求。

如果你不要求实时返回，可以改用标准任务模式 /v3/keywords_data/google/ad_traffic_by_platforms/task_post/，通常成本更低；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

另外，你也可以通过 /v3/keywords_data/google/adwords_status/ 查看平台搜索量数据的更新状态。

容性说明

Google AdWords Keywords Data API 属于旧版能力，现已由 Google Ads API 替代。如果你当前仍在使用旧版容路径，建议逐步迁移至新版接口。

请求地址

POST https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_platforms/live

计费与限额

• 本接口按请求计费
• 参考价约 ¥1.2000 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 每分钟最多可发起 2000 次 API 调用
• 单个 keywords 数组最多可传 2500 个
• 无论 keywords 中传 1 个还是 2500 个，均按单次请求计费

请求体格式

所有 POST 数据使用 JSON（UTF-8 编码），且请求体为 JSON 数组：

[
 {
 "location_name": "United States",
 "language_name": "English",
 "bid": 999.00,
 "match": "exact",
 "keywords": [
 "seo marketing"
 ]
 }
]

请求参数

字段名	类型	说明
keywords	array	填。数组。最多 2500 个；每个最长 80 个字符；每个短语最多 10 个词。系统会将统一转换为小写后处理。
bid	float	填。最大自定义出价。返回的估算数据基于该值计算，表示你愿意为广告支付的价格。通常出价越高，返回的广告位置和价格也会越高。
match	string	填。匹类型。可选值：exact、broad、phrase。
location_name	string	可选。搜索引擎地区名。使用该字段时，无需再传 location_code 或 location_coordinate。可通过 /v3/keywords_data/google/locations 获取可用地区列表。不传则返回结果。示例：London,England,United Kingdom
location_code	integer	可选。搜索引擎地区代码。使用该字段时，无需再传 location_name 或 location_coordinate。可通过 /v3/keywords_data/google/locations 获取可用地区代码。不传则返回结果。示例：2840
location_coordinate	string	可选。地理坐标，格式为 "latitude,longitude"。使用该字段时，无需再传 location_name 或 location_code。结果将按该坐标所属国家返回。不传则返回结果。示例：52.6178549,-155.352142
language_name	string	当未提供 language_code 时填。搜索引擎语言名。使用该字段时，无需再传 language_code。可通过 /v3/keywords_data/google/languages 获取可用语言列表。示例：English
language_code	string	当未提供 language_name 时填。搜索引擎语言代码。使用该字段时，无需再传 language_name。可通过 /v3/keywords_data/google/languages 获取可用语言代码。示例：en
tag	string	可选。用户自定义任务标识，最长 255 个字符。可用于结果对账与任务追踪，响应中的 data 对象会原样返回该值。

返回结果结构

接口返回 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	你在 POST 中提交的参数回显
result	array	结果数组

结果字段说明

result 中会返回三个平台对象：desktop、mobile、tablet。三字段结构基本一致。

平台结果通用字段

字段名	类型	说明
location_code	integer	请求中使用的地区代码；无数据时为 null
language_code	string	请求中使用的语言代码；无数据时为 null
bid	float	请求中提交的最大自定义出价
keyword / keywords	string / array	请求中的信息。部分平台结果中，会以解码后的形式返回，+ 会被还原为空格。
match	string	匹类型：exact、broad、phrase
ad_position_min	float	最低广告位置；无数据时为 null
ad_position_max	float	最高广告位置；无数据时为 null
ad_position_average	float	平均广告位置；无数据时为 null
cpc_min	float	最低历史 CPC，单位 USD；无数据时为 null
cpc_max	float	最高历史 CPC，单位 USD；无数据时为 null
cpc_average	float	平均历史 CPC，单位 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

重要说明

• 平台 API 返回的是广告流量估算值，可能与广告平台规划界面中的数值存在差异。
• 结果可能受到账户历史、已有广告创意及因素影响。
• 如需尽量降低因素对结果的影响，可适当提高 bid 值。
• 未命中数据时，数值字段可能返回 null。

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_platforms/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "location_name": "United States",
 "language_name": "English",
 "bid": 999.00,
 "match": "exact",
 "keywords": [
 "seo marketing"
 ],
 "tag": "ad-traffic-platforms-demo"
 }
]

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.0,
 match: "exact",
 keywords: ["seo marketing"],
 tag: "ad-traffic-platforms-demo",
 },
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_platforms/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": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.6369 sec.",
 "cost": 0.075,
 "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": [
 "seo marketing"
 ]
 },
 "result": [
 {
 "desktop": {
 "language_code": "en",
 "location_code": 2840,
 "bid": 999,
 "keywords": [
 "seo marketing"
 ],
 "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,
 "keywords": [
 "seo marketing"
 ],
 "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,
 "keywords": [
 "seo marketing"
 ],
 "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
 }
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整个请求的处理状态
• tasks[].status_code 表示单个任务的处理状态
• 建议同时检查：
• 顶层 status_code
• tasks_error
• 每个任务的 status_code
• 请为异常场景设计完善的错误处理与重试机制

常见成功标识：

字段	值	含义
status_code	20000	请求成功

更多错误码请参考 /v3/appendix/errors。

使用建议

• 适合需要实时估算广告投放潜力的场景
• 当你心的是组整体在不同设备上的广告表现差异时，本接口比逐接口更高效
• 如果需要对每个分别进行设备级流量预估，应改用逐接口
• 地域与语言参数会直接影响结果，建议明确传 location_* 与 language_* 参数，混用默认值

实用场景

• 评估设备投放优级：比较 desktop、mobile、tablet 的、点击与 CPC，决定预算优投向哪类设备，提升投放效率。
• 测算组预算空间：基于 daily_cost_average 与 daily_clicks_average 预估组合的日消耗和点击规模，广告预算制定。
• 优化多端落地页策略：识别移动端或桌面端流量差异，为不同设备设计专属落地页与转化路径，提升转化率。
• 筛选高价值商业词组：结合广告位、点击和 CPC 估算，快速判断某组是否备商业投放价值，减少试错成本。
• 支持区域化投放决策：按地区与语言组合查询设备表现，本地化 SEO/SEM 团队制定更精细的市场策略。