Google Ads 推荐（Live）

POST /v3/keywords_data/google_ads/keywords_for_keywords/live

接口说明

该接口用于根据给定获取推荐，数据来源于 Google Ads 最新版本能力。你最多可以在 keywords 数组中提交 20 个，接口将返回的建议及核心指标。

• 请求方式：POST
• 接口路径：/v3/keywords_data/google_ads/keywords_for_keywords/live
• 完整地址：https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/live

使用限制

• 每个账号通过 Google Ads Live 系列端点最多可发送 12 次请求/分钟 -局 POST 请求吞吐上限为 2000 次 API 调用/分钟
• 历史数据最长可追溯 4 年
• 单次请求最多可返回 20,000 个建议
• 无论最终返回多少，均按请求次数计费

计费说明

每次请求都会产生费用。 参考价约 ¥1.2000 / 次。

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

请求参数

POST 请求体为 JSON 数组格式：

[
 {
 "keywords": ["seo tools", "keyword research"],
 "location_name": "United States"
 }
]

参数说明

字段名	类型	说明
keywords	array	填。查询的列表。最多 20 个；每个最多 80 个字符；提交后会自动转为小写。注意：某些组可能返回无数据。Google Ads 不部分特殊符号或字符（如 UTF 特殊符号、emoji），因此这些不能用于任务请求。
location_name	string	搜索引擎地区名。可选。不传则返回范围结果。若使用该字段，则无需传 location_code 或 location_coordinate。可通过 /v3/keywords_data/google_ads/locations 获取支持的地区列表。示例：London,England,United Kingdom
location_code	integer	搜索引擎地区编码。可选。不传则返回范围结果。若使用该字段，则无需传 location_name 或 location_coordinate。可通过 /v3/keywords_data/google_ads/locations 获取支持的地区列表。示例：2840
location_coordinate	string	地理坐标。可选。格式为 "latitude,longitude"。若使用该字段，则无需传 location_name 或 location_code。返回的数据将基于该坐标所属国家。示例：52.6178549,-155.352142
language_name	string	搜索语言名。可选。可通过 /v3/keywords_data/google_ads/languages 获取支持语言列表。示例：English
language_code	string	搜索语言代码。可选。可通过 /v3/keywords_data/google_ads/languages 获取支持语言列表。示例：en
search_partners	boolean	是否 Google 搜索合作伙伴数据。可选。true 表示 Google 及合作搜索网络；默认 false，返回 Google 搜索站点数据。
date_from	string	时间范围开始日期。可选。格式：yyyy-mm-dd。最早可设置为当前日期往前 4 年。默认返回过去 12 个月数据。该日期不能晚于 date_to，也不能晚于昨天。若状态接口 /v3/keywords_data/google_ads/status/ 返回 actual_data=false，则最晚只能设置到上上月及更早；若返回 true，则最晚可设置到上个月及更早。
date_to	string	时间范围结束日期。可选。格式：yyyy-mm-dd。不能晚于昨天；如果不传，默认使用昨天。示例：2022-11-30
sort_by	string	结果排序方式。可选。支持按 relevance、search_volume、competition_index、low_top_of_page_bid、high_top_of_page_bid 进行降序排序。默认：relevance
include_adult_keywords	boolean	是否成人。可选。设为 true 时将尝试返回。默认 false。注意：由于 Google Ads 限制，这类可能仍然无数据。
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	任务状态码，范围通常在 10000-60000
status_message	string	任务状态信息
time	string	任务执行耗时
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组数量
path	array	URL 路径信息
data	object	回显请求时提交的参数
result	array	结果数组

result 数组字段

字段名	类型	说明
keyword	string	返回的
location_code	integer	请求中的地区编码；无数据时为 null
language_code	string	请求中的语言编码；无数据时为 null
search_partners	boolean	是否搜索合作伙伴数据
competition	string	付费搜索竞争度反映广告投放层面的相对竞争水平。可能值：LOW、MEDIUM、HIGH；未知时为 null
competition_index	integer	竞争度指数，范围 0-100。值越高，广告位竞争越激烈；数据不足时为 null
search_volume	integer	月均搜索量。根据目标范围不同，表示 Google 或 Google + 合作伙伴网络中的近似搜索次数；无数据时为 null
low_top_of_page_bid	float	广告出现在首页顶部位置所需的较低出价参考值。大致高于最低出价样本中的 20%
high_top_of_page_bid	float	广告出现在首页顶部位置所需的较高出价参考值。大致高于最低出价样本中的 80%
cpc	float	单次点击费用，单位 USD
monthly_searches	array	月度搜索量明细。通常可返回近 12 个月按月分布数据；无数据时为 null
monthly_searches[].year	integer	年份
monthly_searches[].month	integer	月份
monthly_searches[].search_volume	integer	当月搜索量
keyword_annotations	object	附加标注信息
keyword_annotations.concepts	array	概念列表
keyword_annotations.concepts[].name	string	概念名称
keyword_annotations.concepts[].concept_group	object	概念分组信息
keyword_annotations.concepts[].concept_group.name	string	分组名称
keyword_annotations.concepts[].concept_group.type	string	分组类型

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "keywords": [
 "adsense",
 "seo tools"
 ],
 "sort_by": "relevance"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "location_name": "United States",
 "keywords": ["adsense", "seo tools"],
 "sort_by": "relevance"
 }
]

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

TypeScript

import axios from "axios";

const postData = [
 {
 location_name: "United States",
 keywords: ["adsense", "seo tools"],
 sort_by: "relevance"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_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.response?.data || error.message);
 });

响应示例

{
 "version": "0.1.20231117",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.8776 sec.",
 "cost": 0.075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_keywords",
 "se": "google_ads",
 "location_code": 2840,
 "keywords": [
 "adsense"
 ]
 },
 "result": [
 {
 "keyword": "adsense rpm average",
 "location_code": 2840,
 "language_code": null,
 "search_partners": false,
 "competition": "LOW",
 "competition_index": 0,
 "search_volume": 20,
 "low_top_of_page_bid": null,
 "high_top_of_page_bid": null,
 "cpc": null,
 "monthly_searches": null,
 "keyword_annotations": {
 "concepts": null
 }
 }
 ]
 }
 ]
}

状态码与错误处理

请基于 status_code 和 status_message 实现统一的错误处理机制，重点区分以下层级：

• 顶层请求是否成功
• tasks 中是否存在任务级错误
• 某些是否因无数据、地区限制、字符限制或广告政策限制而返回空结果

常见处理建议：

1. 当顶层 status_code 非成功状态时，直接按请求失败处理。
2. 当顶层成功但 tasks_error > 0 时，应遍历 tasks 检查每个任务的 status_code。
3. 当任务成功但 result 为空时，通常表示组无可用数据，或受到地区/字符/政策限制。
4. 对 date_from、date_to 的合法性做预校验，因日期限导致请求失败。
5. 对 keywords做洗，使用不被支持的特殊字符或 emoji。

使用建议

• 优控制单次提交数量，建议按主题分组，以提高性
• 如果需要更聚焦的市场数据，建议明确指定 location_code 与 language_code
• 若要评估广告投放价值，可重点：
• search_volume
• competition_index
• low_top_of_page_bid
• high_top_of_page_bid
• cpc
• 若需分析季节性趋势，可结合 monthly_searches 与自定义时间范围使用
• 对成人或敏感词场景，即使启用 include_adult_keywords=true，也应预期存在较高无数据概率

实用场景

• 挖掘长尾词：核心业务词，批量获取搜索词，扩 SEO库与投放词库。
• 筛选低竞争机会词：结合 search_volume 和 competition_index，发现“有量但竞争较低”的优布局。
• 评估广告投放成本：基于 cpc、low_top_of_page_bid、high_top_of_page_bid 预估商业价值与预算压力。
• 分析季节性：通过 monthly_searches 查看月度波动，制定发布时间和投放节奏。
• 做地区化选词：叠加 location_name、location_code 或 language_code，为不同国家/语言市场生成本地化方案。