SeerMarTech API 文档

主题

Google 分类实时获取 ​

接口概述 ​

POST /v3/keywords_data/google/keywords_for_category/live

该接口用于根据指定的 Google 产品或服务分类，实时返回建议。除本身外，响应中还会以下核心数据：

  • 上月搜索量
  • 过去 12 个月的搜索趋势
  • 当前平均点击价格（CPC）
  • 付费搜索竞争度（competition）

如果你的业务需要实时返回结果，建议使用 Live 方法。与标准任务模式不同，Live 方法无需创建任务再单独获取结果，一次请求即可直接获取数据。

如果你对实时性要求不高，也可以使用标准模式进行异步获取。标准模式通常更经济，但需要分别调用提交与查询接口。

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

容性说明 ​

Google AdWords Keywords Data API 已属于旧版能力，现已由 Google Ads API 替代。 如果你当前仍在使用旧版接口，建议迁移到容的 Google Ads 数据接口体系。

请求地址 ​

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

计费说明 ​

该接口按请求计费，无论本次返回 1 个还是最多 700 个，单次请求价格相同。

  • 单次请求最多返回 700 个建议及核心指标
  • 接口调用频率上限为 2000 次/分钟
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

根据原始示例，响应中曾出现 cost: 0.075（USD），则可按下述方式估算：

  • 参考价约 ¥1.2000 / 次

说明：以上为示例换算，费用请以接口响应中的 cost 字段为准。

请求体格式 ​

所有 POST 数据需使用 JSON（UTF-8）编码提交。 请求体为 JSON 数组 格式：

json
[
 {
 "location_name": "United States",
 "language_name": "English",
 "category_code": 13895
 }
]

请求参数 ​

字段名类型说明
category_codeinteger填。分类 ID。可通过 /v3/keywords_data/google/categories 获取可用的 Google 产品与服务分类列表。也可参考 Google 官方分类 CSV。
location_namestring搜索引擎地区完整名称。可选。如果使用该字段，则无需填写 location_code 或 location_coordinate。可通过 /v3/keywords_data/google/locations 获取。忽略该字段则返回结果。示例：London,England,United Kingdom
location_codeinteger搜索引擎地区编码。可选。如果使用该字段，则无需填写 location_name 或 location_coordinate。可通过 /v3/keywords_data/google/locations 获取。忽略该字段则返回结果。示例：2840
location_coordinatestring地理坐标。可选。如果使用该字段，则无需填写 location_name 或 location_code。格式为 "latitude,longitude"。返回的数据将基于该坐标所属国家。忽略该字段则返回结果。示例：52.6178549,-155.352142
language_namestring搜索引擎语言完整名称。可选。如果使用该字段，则无需填写 language_code。可通过 /v3/keywords_data/google/languages 获取。忽略该字段则返回所有可用语言的结果。示例：English
language_codestring搜索引擎语言代码。可选。如果使用该字段，则无需填写 language_name。可通过 /v3/keywords_data/google/languages 获取。忽略该字段则返回所有可用语言的结果。示例：en
search_partnersboolean是否 Google 搜索合作伙伴网络数据。可选。设为 true 时，将返回 Google 及搜索合作伙伴的数据。默认值：false
sort_bystring结果排序方式。可选。支持按 search_volume 或 relevance 降序排序。默认值：search_volume
keywords_negativearray否定数组。可选。结果中将排除这些词。最多可指定 200 个要排除的词项。系统会自动转换为小写。
tagstring自定义任务标识。可选，最长 255 字符。可用于请求结果匹与业务侧追踪，响应中的 data 对象会返回该值。

响应结构 ​

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

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码。完整错误码请参考 /v3/appendix/errors
status_messagestring通用状态消息
timestring执行耗时，单位秒
costfloat本次所有任务总成本，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务结果数组

tasks 数组中的字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态说明
timestring任务执行耗时，单位秒
costfloat任务成本，单位 USD
result_countintegerresult 数组中的数量
patharray请求路径
dataobject原样返回本次 POST 提交的参数
resultarray结果列表

result 数组中的字段 ​

字段名类型说明
keywordstring返回的
location_codeinteger请求中对应的地区编码；如无数据则为 null
language_codestring请求中对应的语言代码；如无数据则为 null
search_partnersboolean响应是否合作伙伴网络数据
competitionfloat付费搜索竞争度，取值范围 0 到 1。基于 Google Ads 数据；如无数据则为 null
cpcfloat平均点击价格，单位 USD；如无数据则为 null
search_volumeinteger月均搜索量。表示目标范围的近似搜索次数；如无数据则为 null
categoriesarray产品与服务分类列表；如无数据则为 null
monthly_searchesarray最近 12 个月的月度搜索量；如无数据则为 null

monthly_searches 字段 ​

字段名类型说明
yearinteger年份
monthinteger月份
search_volumeinteger当月搜索量

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "language_name": "English",
 "category_code": 13895
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "location_name": "United States",
 "language_name": "English",
 "category_code": 13895
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const postData = [
 {
 location_name: "United States",
 language_name: "English",
 category_code: 13895,
 },
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/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
{
 "version": "0.1.20200130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "5.2880 sec.",
 "cost": 0.075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_category",
 "se": "google",
 "location_name": "London,England,United Kingdom",
 "language_name": "English",
 "category_code": 13895,
 "tag": "tag1"
 },
 "result": [
 {
 "keyword": "polygon",
 "location_code": 1006886,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.0013572539051896456,
 "cpc": 0,
 "search_volume": 6600,
 "categories": [],
 "monthly_searches": []
 },
 {
 "keyword": "mountain bike",
 "location_code": 1006886,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.9998855922507818,
 "cpc": 0.770228,
 "search_volume": 5400,
 "categories": [],
 "monthly_searches": []
 },
 {
 "keyword": "hyundai kona",
 "location_code": 1006886,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.29028968834971763,
 "cpc": 0.860399,
 "search_volume": 4400,
 "categories": [],
 "monthly_searches": []
 }
 ]
 }
 ]
}

状态码与错误处理 ​

  • 顶层 status_code 表示本次请求整体处理状态
  • tasks[].status_code 表示单个任务的执行状态
  • 建议业务系统同时处理：
  • 请求级错误
  • 单任务失败
  • 返回字段为空（如 search_volume、cpc、competition 为 null）

常见成功状态：

  • 20000：请求成功

完整错误码请参考 /v3/appendix/errors。

使用说明与注意事项 ​

  1. category_code 为填字段，调用前应确认分类 ID 是否有效。
  2. location_name、location_code、location_coordinate 三任选一，不应重复传。
  3. language_name 与 language_code 二选一即可。
  4. 若未指定地区，接口将返回范围结果。
  5. 若未指定语言，接口将返回所有可用语言的结果。
  6. keywords_negative 最多支持 200 个排除词，适合过滤品牌词、无词或低价值词。
  7. sort_by 默认按 search_volume 降序返回，更适合优查看高搜索量词。
  8. Live 接口适合交互式系统、实时推荐、在线分析等场景。

实用场景 ​

  • 挖掘分类长尾词：基于指定产品或服务分类批量获取，快速扩展 SEO 选题库与落地页词库。
  • 评估类目投放价值：结合 search_volume、cpc、competition 判断某一类目在自然搜索与付费投放中的商业价值。
  • 筛除无搜索词：使用 keywords_negative 排除品牌词、竞品词或低转化词，提高研究结果的纯度。
  • 监测类目需求趋势：利用 monthly_searches 分析过去 12 个月的搜索变化，识别旺季、淡季与需求波动。
  • 制定区域化策略：通过地区与语言定向获取，支持多国家、多语言站点的本地化 SEO 规划。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API