站点推荐（实时）/v3/keywords_data/google_ads/keywords_for_site/live

接口说明

该接口用于基于指定网站域名或页面 URL，实时返回与的建议，并附带以下核心指标：

• 出价区间
• 上个月搜索量
• 过去一年的搜索量趋势
• 竞争度与竞争指数

本接口基于最新版 Google Ads 数据体系，适合用于站点主题挖掘、投放词发现与 SEO/PPC 联合分析。

限流说明：

• 每个账号对 Google Ads Live 系列接口的调用频率不 12 次/分钟 -平台 POST 请求速率最高可达 2000 次/分钟
• 单次请求最多可返回 2000 个建议

历史数据范围：

• 最长可查询 4 年历史数据
• 默认返回最近 12 个月数据

请求地址

POST https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_site/live

计费说明

该接口按 每次请求 计费，无论最终返回多少都会扣费。

参考价约 ¥1.2000 / 次扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

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

---

请求参数

字段名	类型	填	说明
target	string	是	目标网站域名或目标页面 URL。若希望获取整个网站的，请结合 target_type 使用。
target_type	string	否	发现范围。可选值：site、page；默认值：page。site 表示针对整个站点，page 表示针对指定页面。
location_name	string	否	搜索引擎地区名。不传则返回范围结果。使用该字段时，无需再传 location_code 或 location_coordinate。示例：London,England,United Kingdom
location_code	integer	否	搜索引擎地区编码。不传则返回范围结果。使用该字段时，无需再传 location_name 或 location_coordinate。示例：2840
location_coordinate	string	否	GPS 坐标，格式为 "latitude,longitude"。使用该字段时，无需再传 location_name 或 location_code。数据将按该坐标所属国家返回。示例：52.6178549,-155.352142
language_name	string	否	搜索引擎语言名称。示例：English
language_code	string	否	搜索引擎语言代码。示例：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
include_adult_keywords	boolean	否	是否成人。true 表示，默认值为 false。注意：由于平台广告政策限制，部分此类可能无返回数据。
sort_by	string	否	排序字段，按降序返回。可选值：relevance、search_volume、competition_index、low_top_of_page_bid、high_top_of_page_bid。默认值：relevance
tag	string	否	自定义任务标识，最长 255 个字符。可用于请求与响应结果对应，返回时会原样出现在响应 data 对象中。

地区与语言列表接口

如需获取可用地区或语言列表，可调用以下容路径：

• 地区列表：/v3/keywords_data/google_ads/locations
• 语言列表：/v3/keywords_data/google_ads/languages

---

响应结构

接口返回 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	请求路径
data	object	与请求中提交参数一致
result	array	结果列表

result 数组字段

字段名	类型	说明
keyword	string	返回的
location_code	integer	请求中的地区编码；若无数据则为 null
language_code	string	请求中的语言代码；若无数据则为 null
search_partners	boolean	是否 Google 搜索合作伙伴数据
competition	string	付费搜索竞争度。可选值：LOW、MEDIUM、HIGH；未知时为 null
competition_index	integer	竞争指数，范围 0-100；数据不足时为 null
search_volume	integer	月均搜索量；无数据时为 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_site/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "target": "example.com",
 "target_type": "site",
 "search_partners": true
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_site/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "location_name": "United States",
 "target": "example.com",
 "target_type": "site",
 "search_partners": True
 }
]

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

TypeScript

import axios from "axios";

const postData = [
 {
 location_name: "United States",
 target: "example.com",
 target_type: "site",
 search_partners: true
 }
];

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

---

响应示例

{
 "version": "0.1.20210917",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.6321 sec.",
 "cost": 0.075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_site",
 "se": "google_ads",
 "target": "example.com",
 "location_code": 2840,
 "search_partners": true
 },
 "result": [
 {
 "keyword": "本平台",
 "location_code": 2840,
 "language_code": null,
 "search_partners": true,
 "competition": "LOW",
 "competition_index": 12,
 "search_volume": 110,
 "low_top_of_page_bid": 104.34,
 "high_top_of_page_bid": 264.96,
 "cpc": 3.94,
 "monthly_searches": [],
 "keyword_annotations": {
 "concepts": []
 }
 },
 {
 "keyword": "best seo tools",
 "location_code": 2840,
 "language_code": null,
 "search_partners": true,
 "competition": "MEDIUM",
 "competition_index": 41,
 "search_volume": 2900,
 "low_top_of_page_bid": 130.17,
 "high_top_of_page_bid": 780.74,
 "cpc": 3.94,
 "monthly_searches": [],
 "keyword_annotations": {
 "concepts": []
 }
 },
 {
 "keyword": "top seo tools",
 "location_code": 2840,
 "language_code": null,
 "search_partners": true,
 "competition": "LOW",
 "competition_index": 24,
 "search_volume": 1300,
 "low_top_of_page_bid": 113.83,
 "high_top_of_page_bid": 481.14,
 "cpc": 3.94,
 "monthly_searches": [],
 "keyword_annotations": {
 "concepts": []
 }
 },
 {
 "keyword": "seo tools list",
 "location_code": 2840,
 "language_code": null,
 "search_partners": true,
 "competition": "LOW",
 "competition_index": 18,
 "search_volume": 260,
 "low_top_of_page_bid": 148.09,
 "high_top_of_page_bid": 474.29,
 "cpc": 3.94,
 "monthly_searches": [],
 "keyword_annotations": {
 "concepts": []
 }
 }
 ]
 }
 ]
}

---

状态码与错误处理

• 顶层 status_code 表示整次请求状态
• tasks[].status_code 表示单个任务状态
• 建议业务侧同时处理顶层状态与任务级状态
• 完整错误码与状态信息请参考 /v3/appendix/errors

常见处理建议：

• 当 status_code != 20000 时，优视为请求失败
• 当顶层成功但 tasks_error > 0 时，需逐个检查任务结果
• 当字段返回 null 时，通常表示平台暂无足够数据，而非程序异常

---

使用说明补

1. 如果希望获取整个网站的，请设置：

• target: 网站域名
• target_type: site

2. 如果希望获取单个页面的，请设置：

• target: 页面完整 URL
• target_type: page

3. 地区参数 location_name、location_code、location_coordinate 三只需传一个，重复指定。

4. 语言参数 language_name 与 language_code 建议二选一使用。

5. sort_by 会影响结果排序，但不会影响计费。

实用场景

• 挖掘站点主题词：竞品域名，快速提取高，用于补规划与栏目布局。
• 定位页面投放词：针对单个落地页获取广告词，帮助优化 SEM 分组与出价策略。
• 评估词的商业价值：结合 cpc、competition_index、顶部出价区间，筛选更适合投放或转化的。
• 分析搜索趋势变化：利用 monthly_searches 观察近 12 个月热度波动，识别季节性词与增长型词。
• 对比不同地区机会：切换 location_name 或 location_code 查询不同国家/地区，发现海外市场的流量与竞争差异。