SeerMarTech API 文档

主题

Google 推荐任务创建 ​

POST /v3/keywords_data/google/keywords_for_keywords/task_post

接口说明 ​

该接口用于为指定词语获取建议。一次任务最多可提交 200 个，系统会基于平台搜索广告能力返回与这些词的推荐词。

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

如果您的业务需要即时返回结果，建议使用 实时（Live）方式：/v3/keywords_data/google/keywords_for_keywords/live/。该方式无需拆分为单独的 POST 和 GET 请求。

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

说明：该数据接口属于较早版本能力；如您在新项目中接，建议同时评估本平台容接口方案。

请求地址 ​

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

计费说明 ​

在成功创建任务时扣费。

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

请求方式与频率限制 ​

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

异步回调机制 ​

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

  1. 使用任务唯一标识 id，后续调用结果接口主动查询；
  2. 创建任务时传 postback_url，任务完成后，本平台会将结果以 gzip 压缩的 POST 请求回传到该地址；
  3. 创建任务时传 pingback_url，任务完成后，本平台会向该地址发送 GET 通知。

注意事项：

  • 若您的服务器在 10 秒未响应，连接会因时中止； -时后任务会被转移到 tasks_ready 列表，可通过结果查询流程继续获取；
  • 回调失败时，错误码和错误信息取决于您的服务器；
  • postback_url 和 pingback_url 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23。

请求参数 ​

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

字段名类型说明
keywordsarray填。扩展的列表，最多 200 个。系统会将提交的统一转换为小写，并在结果中按独立数组处理。
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可选。GPS 坐标，格式为 latitude,longitude。若使用该字段，则无需再传 location_name 或 location_code。返回数据将对应于该坐标所属国家。忽略该字段则返回结果。示例：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可选。是否搜索合作伙伴数据。传 true 时，结果覆盖 Google 及搜索合作伙伴。默认值：false
sort_bystring可选。结果排序方式支持按 search_volume 或 relevance 降序排序。默认值：search_volume
keywords_negativearray可选。负向排除列表，这些词不会出现在结果中。最多可指定 200 个排除词，系统会统一转为小写。
closely_variantsboolean可选。是否返回与词高度的结果。传 true 时，keywords_negative 不能与 keywords 中的词相同。默认值：false
postback_urlstring可选。结果回传地址。任务完成后，本平台会以 POST 方式将 gzip 压缩结果发送到该地址。支持在 URL 中使用 $id 作为任务 ID 变量、$tag 作为 URL 编码后的标签变量。示例：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 对象中会返回该值。

响应结构 ​

接口返回 JSON 对象， tasks 数组，每个任务对应一项结果。

顶层响应字段 ​

字段名类型说明
versionstringAPI 当前版本
status_codeinteger通用状态码。完整错误码见 /v3/appendix/errors
status_messagestring通用状态信息
timestring请求执行时间，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务结果数组

tasks 数组字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，由平台 API 生成，范围通常在 10000-60000
status_messagestring任务状态信息
timestring当前任务处理时间，单位秒
costfloat当前任务费用，单位 USD
result_countintegerresult 数组中的数量
patharray请求路径
dataobject您在 POST 中提交的任务参数
resultarray | null结果数组。对于 task_post 创建任务接口，此处通常为 null

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_keywords/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ]
 },
 {
 "language_code": "en",
 "location_code": 2840,
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ],
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ],
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_keywords/task_post"

payload = [
 {
 "location_name": "United States",
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ]
 },
 {
 "language_code": "en",
 "location_code": 2840,
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ],
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ],
 "postback_url": "https://your-server.com/postbackscript"
 }
]

headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 location_name: "United States",
 keywords: [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ]
 },
 {
 language_code: "en",
 location_code: 2840,
 keywords: [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ],
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 location_name: "United States",
 language_name: "English",
 keywords: [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ],
 postback_url: "https://your-server.com/postbackscript"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_keywords/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 // 处理返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例 ​

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-5d6b3f92a123",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "keywords_for_keywords",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_keywords",
 "se": "google",
 "location_name": "United States",
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ]
 },
 "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_keywords",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_keywords",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ],
 "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_keywords",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_keywords",
 "se": "google",
 "language_name": "English",
 "location_name": "United States",
 "keywords": [
 "average page rpm adsense",
 "adsense blank ads how long",
 "leads and prospects"
 ],
 "postback_url": "https://your-server.com/postbackscript"
 },
 "result": null
 }
 ]
}

常见状态与错误说明 ​

代码说明
20000请求成功
20100任务已创建
40006单次 POST 中任务数 100 个
错误请参考 /v3/appendix/errors，并在业务中做好异常处理与重试机制

使用建议 ​

  • 适合批量提交拓展任务，异步获取结果；
  • 如果对时效要求较高，优使用 /v3/keywords_data/google/keywords_for_keywords/live/；
  • 建议在生产环境中为每个任务设置 tag，便于回溯和对账；
  • 如果采用回调模式，请确保回调服务在 10 秒返回成功响应；
  • 当需要限定国家、语言或搜索合作伙伴范围时，优显式传对应参数，结果范围过宽。

实用场景 ​

  • 扩展投放词库：种子词批量获取建议，快速沉淀广告投放或 SEO规划词库。
  • 筛除无方向：结合 keywords_negative 排除不想覆盖的主题词，提升推荐结果的业务性。
  • 按国家语言做本地化选词：通过 location_code、language_code 获取特定市场的建议，支持出海站点或本地站点运营。
  • 构建异步生产流水线：结合 pingback_url 或 postback_url，实现“创建任务—回调库—自动分析”的自动化处理流程。
  • 聚焦高候选词：启用 closely_variants 保留高度变体，帮助团队缩小选题范围、提高产出效率。

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

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