Google 广告流量预估（实时）

接口说明

该接口用于实时获取一组的广告流量预估数据：

• 每日展示量预估
• 平均点击成本（CPC）预估
• 每日点击量预估

相比常规搜索量数据，这类广告流量预估通常更适合评估某个的真实商业需求，因为它反映的是广告投放维度下的估算结果，而不是一组相似的广泛匹搜索量。

需要注意：

• 平台 API 返回的结果可能与广告平台规划中看到的数值存在差异；
• 返回结果会受到账户历史、广告素材及因素影响；
• 若希望尽量弱化这些因素的影响，通常建议设置较高的 bid。

如果你的系统需要即时返回结果，建议使用当前的 Live 实时接口。 如果不要求实时返回，也可以使用对应的 Standard 方式，通过分开的 POST / GET 流程获取结果，成本通常更低。

此外，如需查看 Google API 返回的搜索量更新状态，可使用 /v3/keywords_data/google/adwords_status/。

接口地址

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

计费说明

该接口按请求次数计费。

• 单次请求最多可提交 2500 个
• 无论 keywords 数组中 1 个还是 2500 个，都按一次请求计费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

接口限频：

• 最多 2000 次 API 调用 / 分钟

请求格式

• 请求方法：POST
• 编码格式：JSON（UTF-8）
• 请求体为 JSON 数组：[{ ... }]

请求参数

字段名	类型	填	说明
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 对象中。

请求示例

curl

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_keywords/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

import requests

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

response = requests.post(url, headers=headers, json=data)
print(response.json)

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_keywords/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);
 });

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表可参考 /v3/appendix/errors
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，完整列表参考 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	当前任务成本（平台为 USD）
result_count	integer	result 数组中的结果数量
path	array	URL 路径
data	object	与提交时相同的请求参数
result	array	结果数组

result[] 字段

每个对应一个的广告流量预估结果。

字段名	类型	说明
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	历史最小单次点击成本（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

响应示例

{
 "version": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.5868 sec.",
 "cost": 0.075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "2d9b7f4e-5d7d-4c9f-9d18-1234567890ab",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.5868 sec.",
 "cost": 0.075,
 "result_count": 1,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "ad_traffic_by_keywords",
 "live"
 ],
 "data": {
 "api": "keywords_data",
 "function": "ad_traffic_by_keywords",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "bid": 999,
 "match": "exact",
 "keywords": [
 "seo marketing"
 ]
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": "en",
 "bid": 999,
 "keyword": "seo marketing",
 "match": "exact",
 "ad_position_min": 1,
 "ad_position_max": 3,
 "ad_position_average": 2,
 "cpc_min": 1.25,
 "cpc_max": 3.8,
 "cpc_average": 2.4,
 "daily_impressions_min": 120,
 "daily_impressions_max": 260,
 "daily_impressions_average": 190,
 "daily_clicks_min": 8,
 "daily_clicks_max": 21,
 "daily_clicks_average": 14,
 "daily_cost_min": 10,
 "daily_cost_max": 79.8,
 "daily_cost_average": 33.6
 }
 ]
 }
 ]
}

返回状态码

顶层状态码

状态码	说明
20000	请求成功

任务状态码

任务级别的 status_code 用于表示单个任务执行。 完整错误码与说明请参考 /v3/appendix/errors。

使用建议

1. 数量较多时优批量提交：单次最多支持 2500 个，适合做大规模需求评估。
2. 优明确语言与地区：否则拿到的是或默认维度结果，可能不适用于本地化投放分析。
3. 合理设置 bid：该参数直接影响预估结果，过低可能导致流量、排名和成本估算偏保守。
4. 注意空值处理：若某些缺少广告历史数据，多个预估字段可能返回 null。

实用场景

• 评估投放价值：批量比较的展示量、点击量和 CPC，筛选更商业价值的投放词。
• 制定广告预算：基于 daily_cost_* 与 daily_clicks_* 估算日预算区间，提前评估获客成本。
• 筛选高需求：结合 daily_impressions_average 判断真实市场需求， SEO 与 SEM 选词。
• 优化地区投放策略：按不同 location_name 或 location_code 获取数据，对比不同国家/地区的流量潜力。
• 验证匹类型差异：分别请求 exact、phrase、broad，评估不同匹方式下的流量与成本变化。