SeerMarTech API 文档

主题

Google 分类任务提交 ​

接口说明 ​

该接口用于基于指定的 Google 产品或服务分类，获取建议任务。任务完成后，结果中除了本身，还会以下核心数据：

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

这是标准异步模式接口，适合不要求实时返回结果的场景。您创建任务，平台采集完成后，再通过结果接口查询数据。执行时间取决于系统负载。

如果业务需要即时获取结果，建议使用对应的 实时（Live）接口 /v3/keywords_data/google/keywords_for_category/live/，无需分两步进行 POST 提交和 GET 获取。

此外，您还可以通过 /v3/keywords_data/google/adwords_status/ 查看平台搜索量数据的更新时间状态。通常数据会在每月月中更新。

说明：该组数据接口属于旧版能力，当前已由 Google Ads API 体系替代。如您正在使用旧版能力，建议规划迁移到容的新接口体系。

请求地址 ​

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

计费说明 ​

该接口按任务提交次数计费，而不是按返回数量计费。

  • 单次请求最多可返回约 700 个建议及核心指标
  • 无论最终返回 1 个还是 700 个，单个任务计费一致
  • 参考价约 ¥0.8000 / 次
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求方式与限制 ​

  • 请求方法：POST
  • 请求体格式：JSON 数组 [{...}]
  • 编码：UTF-8
  • 单次 POST 最多可提交 100 个任务
  • 每分钟最多可发起 2000 次 API 调用
  • 若单次 POST 中任务数 100，出部分将返回错误 40006

结果获取方式 ​

任务提交后，您可以通过以下方式获取结果：

  1. 使用任务唯一标识 id 查询已完成任务结果
  2. 创建任务时设置 postback_url，平台会在任务完成后主动推送结果
  3. 创建任务时设置 pingback_url，平台会在任务完成后发送完成通知

回调说明 ​

  • postback_url：平台会以 POST 方式推送结果，为 gzip 压缩格式
  • pingback_url：平台会以 GET 方式发送任务完成通知
  • 若您的服务端在 10 秒未响应，请求会因时被中断，任务会转对应的 tasks_ready 列表拉取
  • 回调 URL 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23

请求参数 ​

以下为创建任务时可使用的字段说明。

字段名类型说明
category_codeinteger填。分类 ID。可通过 /v3/keywords_data/google/categories 获取可用的 Google 产品与服务分类列表。
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 个词条；平台会将这些统一转换为小写。
postback_urlstring结果推送地址。可选。任务完成后，平台会向该地址发送 POST 请求，并附带 gzip 压缩结果。支持在 URL 中使用 $id 和 $tag 变量。示例：http://your-server.com/postbackscript?id=$id
pingback_urlstring完成通知地址。可选。任务完成后，平台会向该地址发送 GET 请求。支持在 URL 中使用 $id 和 $tag 变量。示例：http://your-server.com/pingscript?id=$id&tag=$tag
tagstring自定义任务标识。可选。最长 255 个字符。可用于将任务与业务侧记录进行；响应中的 data 对象会原样返回该值。

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "category_code": 13895
 },
 {
 "language_code": "en",
 "location_code": 2840,
 "category_code": 13895,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "category_code": 13895,
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

data = [
 {
 "location_name": "United States",
 "category_code": 13895
 },
 {
 "language_code": "en",
 "location_code": 2840,
 "category_code": 13895,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "category_code": 13895,
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const postData = [
 {
 location_name: "United States",
 category_code: 13895
 },
 {
 language_code: "en",
 location_code: 2840,
 category_code: 13895,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 location_name: "United States",
 language_name: "English",
 category_code: 13895,
 postback_url: "https://your-server.com/postbackscript"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_post",
 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 数组，每个任务对应一项结果。

顶层字段 ​

字段名类型说明
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您在请求中提交的参数回显
resultarray / null结果数组。创建任务成功时，该字段通常为 null，结果需后续查询

响应示例 ​

json
{
 "version": "0.1.20200130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0683 sec.",
 "cost": 0.15,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "01301831-1535-0107-0000-65a7595bdcb8",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0019 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "keywords_for_category",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_category",
 "se": "google",
 "location_name": "United States",
 "category_code": 13895
 },
 "result": null
 },
 {
 "id": "01301831-1535-0107-0000-21cc045291e0",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0020 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "keywords_for_category",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_category",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "category_code": 13895,
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "tag": "some_string_123"
 },
 "result": null
 },
 {
 "id": "01301831-1535-0107-0000-77a3219d7e0b",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0022 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "keywords_for_category",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_category",
 "se": "google",
 "language_name": "English",
 "location_name": "United States",
 "category_code": 13895,
 "postback_url": "https://your-server.com/postbackscript"
 },
 "result": null
 }
 ]
}

状态码与错误处理 ​

  • 20000：请求成功
  • 20100：任务已创建
  • 40006：单次 POST 中任务数上限（100）

建议业务侧基于顶层 status_code 与每个任务的 status_code 做双层校验，并为异步任务建立异常处理与重试机制。完整错误码定义可参考 /v3/appendix/errors。

使用建议 ​

  • 通过 /v3/keywords_data/google/categories 获取最新分类 ID，再创建任务
  • 若需要限定国家或城市维度，优使用 location_code
  • 若需要按广告投放维度评估词机会，可结合 search_partners、CPC 与竞争度进行筛选
  • 如果需要自动化批量处理，建议合 pingback_url 或 postback_url 建立异步回流链路

实用场景 ​

  • 挖掘分类长尾词：针对某一产品或服务分类批量获取，快速扩 SEO 词库与广告投放词。
  • 评估新类目市场需求：结合上月搜索量与年度趋势，判断某个分类的用户需求规模和季节性变化。
  • 筛选高商业价值：利用 CPC 与竞争度识别更适合投放或着陆页建设的商业意图词。
  • 排除无词流量：通过 keywords_negative 过滤品牌无、误匹或低转化词，提升分析质量。
  • 搭建异步采集流程：通过 pingback_url 或 postback_url 实现任务完成自动通知，便于批量生产与数据库。

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

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