主题
Google 广告按平台获取流量估算（实时）
本接口使用 POST 方法，路径为：
/v3/keywords_data/google/ad_traffic_by_platforms/live
本接口用于根据一组获取 Google 广告流量估算数据，并分别返回桌面端、移动端和平板端的每日展示次数、点击次数、平均点击价格（CPC）、每日广告费用及广告排名区间。
这是实时接口，提交请求后会直接返回结果，无需创建任务、再通过 GET 请求查询。若对实时性要求不高，可使用标准任务接口 /v3/keywords_data/google/ad_traffic_by_platforms/task_post 和对应的结果查询接口，以降低成本。
> 估算结果可能与规划中的数据存在差异。平台平台会根据广告账户历史、账户中已有的广告素材及因素生成账户结果。提高 bid 值有助于降低这些因素对估算结果的影响。
计费与请求限制
- 每次请求单独计费，与
keywords数组中的数量无。 - 单次请求最多提交 2500 个；提交 1 个或 2500 个的请求单价相同。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
- 参考价约 ¥0.54 / 次。扣费以响应头
X-SeerMarTech-Charge-CNY为准。
所有 POST 数据使用 UTF-8 编码的 JSON 格式，并且请求体是 JSON 数组：
json
[
{
"keywords": ["seo marketing"],
"bid": 999,
"match": "exact",
"location_name": "United States",
"language_name": "English"
}
]请求参数
| 参数 | 类型 | 填 | 说明 |
|---|---|---|---|
keywords | array | 是 | 要查询的列表。最多 2500 个；每个最多 80 个字符、最多 10 个单词。会被转换为小写，结果会在相应平台对象中返回。 |
bid | float | 是 | 最大自定义出价。估算数据将基于该出价计算。出价越高，预计广告排名和广告费用通常越高。 |
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 | 否 | 位置 GPS 坐标，格式为 纬度,经度，例如 52.6178549,-155.352142。数据将按该坐标所属国家返回。使用此参数时，不要同时提交 location_name 或 location_code。 |
language_name | string | 条件填 | 搜索引擎语言名称。未提交 language_code 时填。使用此参数时，不要同时提交 language_code。示例：English。 |
language_code | string | 条件填 | 搜索引擎语言代码。未提交 language_name 时填。使用此参数时，不要同时提交 language_name。示例：en。 |
tag | string | 否 | 自定义任务标识，最多 255 个字符。可用于将请求与响应进行，提交的值会在响应的 data 对象中返回。 |
可通过以下接口查询可用的位置和语言：
- 位置列表：
/v3/keywords_data/google/locations - 语言列表：
/v3/keywords_data/google/languages
响应结构
接口返回 JSON 数据，顶层 tasks 数组。
顶层字段
| 字段 | 类型 | 说明 |
|---|---|---|
version | string | 当前 API 版本。 |
status_code | integer | 通用状态码。成功时通常为 20000。 |
status_message | string | 通用状态消息。 |
time | string | 请求执行耗时，例如 1.6369 sec.。 |
cost | float | 平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。 |
tasks_count | integer | tasks 数组中的任务数量。 |
tasks_error | integer | tasks 数组中返回错误的任务数量。 |
tasks | array | 任务结果数组。 |
任务字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务唯一标识，UUID 格式。 |
status_code | integer | 任务状态码，通常在 10000 至 60000 范围。 |
status_message | string | 任务状态消息。 |
time | string | 任务执行耗时。 |
cost | float | 平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。 |
result_count | integer | result 数组中的数量。 |
path | array | 请求 URL 路径。 |
data | object | 请求中提交的参数。 |
result | array | 广告流量估算结果。 |
完整状态码和错误码请参考错误码文档。
平台结果字段
result 中通常以下三个平台对象：
desktop：桌面端结果mobile：移动端结果tablet：平板端结果
每个平台对象的字段结构一致。
| 字段 | 类型 | 说明 |
|---|---|---|
location_code | integer | 请求中的位置代码。无数据时为 null。 |
language_code | string | 请求中的语言代码。无数据时为 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 | 历史最低平均点击价格。无数据时为 null。 |
cpc_max | float | 历史最高平均点击价格。无数据时为 null。 |
cpc_average | float | 历史平均点击价格。无数据时为 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。 |
> cpc_* 和 daily_cost_* 为广告费用估算字段，金额单位及扣费信息以本平台响应为准。
curl 请求示例
bash
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"
]
}
]'Python 请求示例
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",
}
post_data = [
{
"location_name": "United States",
"language_name": "English",
"bid": 999.00,
"match": "exact",
"keywords": ["seo marketing"],
}
]
response = requests.post(url, headers=headers, json=post_data)
result = response.json()
if result.get("status_code") == 20000:
print(result)
else:
print(
"请求失败，状态码：{}，消息：{}".format(
result.get("status_code"),
result.get("status_message"),
)
)TypeScript 请求示例
typescript
import axios from "axios";
const postData = [
{
location_name: "United States",
language_name: "English",
bid: 999.0,
match: "exact",
keywords: ["seo marketing"],
},
];
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: postData,
})
.then((response) => {
// 处理响应数据
console.log(response.data);
})
.catch((error) => {
console.error("请求失败：", error.response?.data || error.message);
});响应示例
json
{
"version": "3.20191128",
"status_code": 20000,
"status_message": "Ok.",
"time": "1.6369 sec.",
"cost": 0.54,
"tasks_count": 1,
"tasks_error": 0,
"tasks": [
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"status_code": 20000,
"status_message": "Ok.",
"time": "1.6369 sec.",
"cost": 0.54,
"result_count": 1,
"path": [
"v3",
"keywords_data",
"google",
"ad_traffic_by_platforms",
"live"
],
"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,
"keyword": "seo marketing",
"match": "exact",
"ad_position_min": 1.11,
"ad_position_max": 1.00,
"ad_position_average": 1.06,
"cpc_min": 310.54,
"cpc_max": 379.58,
"cpc_average": 345.10,
"daily_impressions_min": 82.74,
"daily_impressions_max": 101.13,
"daily_impressions_average": 91.94,
"daily_clicks_min": 0.70,
"daily_clicks_max": 0.86,
"daily_clicks_average": 0.78,
"daily_cost_min": 242.57,
"daily_cost_max": 296.50,
"daily_cost_average": 269.57
},
"mobile": {
"language_code": "en",
"location_code": 2840,
"bid": 999,
"keyword": "seo marketing",
"match": "exact",
"ad_position_min": 1.11,
"ad_position_max": 1.00,
"ad_position_average": 1.06,
"cpc_min": 232.63,
"cpc_max": 284.33,
"cpc_average": 258.48,
"daily_impressions_min": 56.11,
"daily_impressions_max": 68.58,
"daily_impressions_average": 62.34,
"daily_clicks_min": 0.40,
"daily_clicks_max": 0.49,
"daily_clicks_average": 0.45,
"daily_cost_min": 103.97,
"daily_cost_max": 126.99,
"daily_cost_average": 115.49
},
"tablet": {
"language_code": "en",
"location_code": 2840,
"bid": 999,
"keyword": "seo marketing",
"match": "exact",
"ad_position_min": 1.11,
"ad_position_max": 1.00,
"ad_position_average": 1.06,
"cpc_min": 203.33,
"cpc_max": 248.47,
"cpc_average": 225.86,
"daily_impressions_min": 1.55,
"daily_impressions_max": 1.90,
"daily_impressions_average": 1.73,
"daily_clicks_min": 0.04,
"daily_clicks_max": 0.04,
"daily_clicks_average": 0.04,
"daily_cost_min": 8.06,
"daily_cost_max": 9.86,
"daily_cost_average": 9.00
}
}
]
}
]
}注意事项
location_name、location_code和location_coordinate三只能选择一个。language_name和language_code二只能选择一个，且至少提交一个。- 单次请求最多 2500 个。
result中的平台对象可能返回空值或null字段，调用方应做好无数据处理。- 建议根据
status_code和status_message实现异常处理及重试策略。 - 实时接口直接返回结果，不需要额外调用任务查询接口。
实用场景
- 比较不同设备的广告流量：分别分析桌面端、移动端和平板端的展示与点击潜力，优化跨设备投放预算。
- 评估投放成本：结合
cpc_average和daily_cost_average估算的广告获客成本，筛选更商业价值的词组。 - 制定地区化投放策略：按国家、城市或搜索位置提交，比较不同市场的广告排名和流量规模。
- 模拟不同出价方案：调整
bid后实时获取排名、展示、点击和费用区间，为出价策略提供量化依据。 - 规划 SEO 与广告协同策略：识别高展示、高点击或高 CPC ，决定哪些词适合优进行自然搜索优化。