SeerMarTech API 文档

主题

创建 Google 搜索量任务 ​

POST /v3/keywords_data/google/search_volume/task_post

接口说明 ​

说明：这是旧版的 Google AdWords 搜索量接口能力，现已被 Google Ads API 替代。若你仍在使用旧版数据链路，建议迁移到 /v3/keywords_data/google_ads/ 接口。

该接口用于提交异步任务，获取的以下数据：

  • 最近一个月的搜索量
  • 最近一年的搜索量趋势
  • 当前点击单价（CPC）
  • 付费搜索竞争度（competition）

这是标准异步获取方式。如果你的业务不要求实时返回结果，推荐使用本接口：创建任务，系统处理完成后，再通过结果接口获取数据。任务执行时间取决于系统负载。

如果你需要即时返回结果，可改用 /v3/keywords_data/google/search_volume/live/。Live 方式无需分开调用 POST 与 GET 接口。

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

请求地址 ​

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

计费说明 ​

该接口按创建任务计费，只要任务创建成功即会产生费用。

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

请求格式与限额 ​

  • 请求体为 UTF-8 编码的 JSON
  • POST 请求体格式为 JSON 数组：[{ ... }]
  • 每分钟最多可发送 2000 次 API 调用
  • 每次 POST 最多可 100 个任务
  • 若单次 POST过 100 个任务，出部分会返回错误 40006
  • 每个任务中的 keywords 数组最多可传 700 个
  • 每个最大长度 80 个字符
  • 每个短语最多 10 个单词

注意：系统按请求次数/任务数计费，而不是按个数计费。同一个任务中传 1 个或 700 个，任务价格相同。

结果获取方式 ​

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

  1. 使用返回的任务唯一标识 id，调用对应结果接口主动拉取；
  2. 创建任务时设置 postback_url，任务完成后本平台会将结果以 gzip 压缩的 POST 请求推送到你的地址；
  3. 创建任务时设置 pingback_url，任务完成后本平台会向你的地址发送 GET 通知。

如果你的服务器在 10 秒未响应回调请求，连接会因时中止，任务会被转 tasks_ready 列表中你主动获取。错误码与报错信息取决于你的服务器。

请求参数 ​

字段名类型说明
keywordsarray**填。**数组。最多 700 个；每个最多 80 个字符；每个短语最多 10 个单词。系统会自动将转为小写，返回结果会按单个拆分。
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搜索引擎语言名。可选。**不建议使用。**如果传该字段，平台可能返回 null 搜索量。若使用该字段，则无需传 language_code。可通过 /v3/keywords_data/google/languages 获取语言列表。示例：English
language_codestring搜索引擎语言代码。可选。**不建议使用。**如果传该字段，平台可能返回 null 搜索量。若使用该字段，则无需传 language_name。可通过 /v3/keywords_data/google/languages 获取语言编码。示例：en
search_partnersboolean是否 Google 搜索合作伙伴数据。可选。传 true 时，结果会 Google 及搜索合作伙伴；默认值为 false。
postback_urlstring结果回传地址。可选。任务完成后，本平台会向该地址发送 POST 请求，并以 gzip 压缩结果。支持在 URL 中使用 $id 和 $tag 占位符，发送时会自动替换为真实值。示例：http://your-server.com/postbackscript?id=$id 或 http://your-server.com/postbackscript?id=$id&tag=$tag。注意：特殊字符会进行 URL 编码，如 # 会被编码为 %23。
pingback_urlstring完成通知地址。可选。任务完成后，本平台会向该地址发送 GET 请求。支持在 URL 中使用 $id 和 $tag 占位符，发送时会自动替换为真实值。示例：http://your-server.com/pingscript?id=$id 或 http://your-server.com/pingscript?id=$id&tag=$tag。注意：特殊字符会进行 URL 编码，如 # 会被编码为 %23。
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 数组中的数量
patharrayURL 路径
dataobject与创建任务时传参数一致
resultarray结果数组。在 task_post 场景中，该值为 null，因为这里只负责创建任务，不直接返回数据结果

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google/search_volume/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"
 ]
 },
 {
 "language_code": "en",
 "location_code": 2840,
 "keywords": [
 "adsense blank ads how long"
 ],
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "keywords": [
 "leads and prospects"
 ],
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python ​

python
import requests

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

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

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

TypeScript ​

typescript
import axios from "axios";

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

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

响应示例 ​

json
{
 "version": "0.1.20200130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0882 sec.",
 "cost": 0.15,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "01302137-1535-0110-0000-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0019 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "search_volume",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "search_volume",
 "se": "google",
 "location_name": "United States",
 "keywords": [
 "average page rpm adsense"
 ]
 },
 "result": null
 },
 {
 "id": "01302137-1535-0110-0000-af164848a289",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0020 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "search_volume",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "search_volume",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "keywords": [
 "adsense blank ads how long"
 ],
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "tag": "some_string_123"
 },
 "result": null
 },
 {
 "id": "01302137-1535-0110-0000-6aa9f0d703d5",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "search_volume",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "search_volume",
 "se": "google",
 "location_name": "United States",
 "language_name": "English",
 "keywords": [
 "leads and prospects"
 ],
 "postback_url": "https://your-server.com/postbackscript"
 },
 "result": null
 }
 ]
}

状态码说明 ​

状态码含义
20000请求成功
20100任务已创建
40006单次 POST 中的任务数 100 个

更多错误码及异常处理规则可参考 /v3/appendix/errors。建议在接时设计完整的重试、告警与异常分流机制。

使用建议 ​

  • 若只需要周期性批量获取搜索量数据，优使用本异步接口，成本与吞吐更友好。
  • 若要控制地区，location_name、location_code、location_coordinate 三只传一个即可。
  • language_name 与 language_code 虽可用，但官方并不推荐；在部分平台会返回 null 搜索量。
  • 对于大规模集，建议按业务批次拆分任务，并结合 tag 做结果归因。
  • 如果接回调，请确保服务端能在 10 秒响应，并支持处理 gzip 压缩。

实用场景 ​

  • 批量评估需求：一次提交大量候选词，获取月搜索量与年度趋势，帮助 SEO 团队快速筛选值得布局的主题。
  • 比较地区市场热度：按不同 location_name 或 location_code 提交同一批，判断不同国家或城市的搜索需求差异，用于本地化与站选题。
  • 监测投放词商业价值：结合返回的 CPC 与竞争度指标，识别高商业意图，为 SEO 与 SEM 协同选词提供依据。
  • 构建异步词量采集流程：通过 pingback_url 或 postback_url 接自动回调，在大规模库更新时减少人工轮询与系统。
  • 跟踪热度变化：利用年度趋势数据观察搜索量波动，识别季节性词、爆发词和衰退词，发布节奏与专题策划。

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

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