SeerMarTech API 文档

主题

设置 Google Ads 搜索量任务 ​

POST /v3/keywords_data/google_ads/search_volume/task_post

接口概述 ​

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

本接口用于创建 Google Ads 搜索量任务，一次请求最多提交 1000 个，可获取搜索量、月度搜索量、竞争程度及指标。

这是异步的标准任务模式：

  1. 调用本接口提交任务；
  2. 通过任务 ID 查询结果；
  3. 或 postback_url / pingback_url，在任务完成后接收通知。

如果业务需要实时返回结果，可改用 Live 接口：

/v3/keywords_data/google_ads/search_volume/live

历史数据最长可追溯 4 年。

> 本接口基于新版 Google Ads API，不再使用旧版 Google AdWords API。

计费说明 ​

  • 在成功创建任务时计费。
  • 一个请求中的 keywords 数量不会影响任务单价，提交 1 个或 1000 个的计费规则相同。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 每次 POST 请求最多 100 个任务； 100 个的任务将返回错误码 40006。
  • 每个任务最多 1000 个。

请求参数 ​

请求体使用 UTF-8 编码的 JSON 数组格式：

json
[
  {
    "keywords": ["buy laptop", "cheap laptops for sale"],
    "location_name": "United States",
    "language_code": "en"
  }
]

任务字段 ​

字段类型填说明
keywordsarray是数组。最多 1000 个；每个最多 80 个字符、最多 10 个单词。会被转换为小写格式。
location_namestring否搜索引擎位置的完整名称，例如 London,England,United Kingdom。未指定时返回范围结果。使用此字段后，无需同时指定 location_code 或 location_coordinate。
location_codeinteger否搜索引擎位置代码，例如 2840。未指定时返回范围结果。使用此字段后，无需同时指定 location_name 或 location_coordinate。
location_coordinatestring否位置 GPS 坐标，格式为 "纬度,经度"，例如 52.6178549,-155.352142。数据将按该坐标所属国家返回。使用此字段后，无需同时指定 location_name 或 location_code。
language_namestring否搜索引擎语言完整名称，例如 English。
language_codestring否搜索引擎语言代码，例如 en。
search_partnersboolean否是否 Google 搜索合作伙伴网络的数据。true 表示 Google 及合作伙伴网站；默认值为 false，返回 Google 搜索网站数据。
date_fromstring否数据起始日期，格式为 yyyy-mm-dd。默认返回过去 12 个月的数据，最早可查询当前日期往前 4 年的数据。该日期不能晚于 date_to 或昨天。
date_tostring否数据结束日期，格式为 yyyy-mm-dd。不能晚于上个月，因为当前月份通常没有完整数据。未指定时默认使用昨天日期。示例：2022-11-30。
include_adult_keywordsboolean否是否与成人的。默认值为 false。即使设为 true，受广告政策限制，部分仍可能无数据。
sort_bystring否结果排序字段，支持 relevance、search_volume、competition_index、low_top_of_page_bid、high_top_of_page_bid。结果按降序排列。默认值为 relevance。
postback_urlstring否任务完成后接收结果的 POST 地址。结果将以 gzip 压缩格式发送。
pingback_urlstring否任务完成后接收通知的 GET 地址。
tagstring否自定义任务标识，最长 255 个字符。可用于任务与结果，提交的值会出现在响应的 data 中。

位置和语言查询 ​

可通过以下接口获取可用的位置和语言列表：

  • 位置列表：/v3/keywords_data/google_ads/locations
  • 语言列表：/v3/keywords_data/google_ads/languages

日期限制 ​

当 /v3/keywords_data/google_ads/status 的 actual_data 为：

  • false：date_from 最早可设置为上上个月及更早日期；
  • true：date_from 最早可设置为上个月及更早日期。

限制与注意事项 ​

  • 某些组合可能没有搜索量数据。
  • 对于相似，Google Ads 可能返回合并后的搜索量。
  • 如需分别获取相似的搜索量，建议将拆分到不同请求中。
  • 不支持部分特殊符号、Unicode 符号或表符号。
  • 提交前应检查长度、单词数量及字符限制。

回调通知 ​

postback_url ​

任务完成后，本平台会向指定地址发送 POST 请求。URL 中可以使用以下变量：

  • $id：任务 ID；
  • $tag：经过 URL 编码的任务标签。

示例：

text
https://your-server.com/postbackscript?id=$id&tag=$tag

pingback_url ​

任务完成后，本平台会向指定地址发送 GET 请求。

示例：

text
https://your-server.com/pingscript?id=$id&tag=$tag

URL 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23。

如果回调服务器在 10 秒未响应，连接将因时中断，任务会转移至任务就绪列表：

/v3/keywords_data/google_ads/search_volume/tasks_ready

响应字段 ​

接口返回 JSON 数据 tasks 数组。

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求级状态码。
status_messagestring请求级状态信息。
timestring请求执行耗时，例如 0.0890 sec.。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray已创建任务的数组。

tasks 子字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。可用于后续获取任务结果。
status_codeinteger任务状态码，通常位于 10000 至 60000 范围。
status_messagestring任务状态信息。
timestring任务执行耗时。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。创建任务时通常为 0。
patharray请求 URL 路径信息。
dataobject创建任务时提交的参数。
resultarray/null任务结果。创建任务接口返回时为 null。

请求示例 ​

curl ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "keywords": [
        "buy laptop",
        "cheap laptops for sale",
        "purchase laptop"
      ]
    },
    {
      "location_code": 2840,
      "keywords": [
        "buy laptop",
        "cheap laptops for sale",
        "purchase laptop"
      ],
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    },
    {
      "location_name": "United States",
      "keywords": [
        "buy laptop",
        "cheap laptops for sale",
        "purchase laptop"
      ],
      "postback_url": "https://your-server.com/postbackscript"
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_post"

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

post_data = [
    {
        "location_name": "United States",
        "keywords": [
            "buy laptop",
            "cheap laptops for sale",
            "purchase laptop",
        ],
    },
    {
        "location_code": 2840,
        "keywords": [
            "buy laptop",
            "cheap laptops for sale",
            "purchase laptop",
        ],
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
    },
    {
        "location_name": "United States",
        "keywords": [
            "buy laptop",
            "cheap laptops for sale",
            "purchase laptop",
        ],
        "postback_url": "https://your-server.com/postbackscript",
    },
]

response = requests.post(url, headers=headers, json=post_data)
response.raise_for_status()

result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：%s，信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript ​

typescript
import axios from "axios";

const postData = [
  {
    location_name: "United States",
    keywords: [
      "buy laptop",
      "cheap laptops for sale",
      "purchase laptop",
    ],
  },
  {
    location_code: 2840,
    keywords: [
      "buy laptop",
      "cheap laptops for sale",
      "purchase laptop",
    ],
    tag: "some_string_123",
    pingback_url:
      "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
  {
    location_name: "United States",
    keywords: [
      "buy laptop",
      "cheap laptops for sale",
      "purchase laptop",
    ],
    postback_url: "https://your-server.com/postbackscript",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_post",
    postData,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理任务创建结果
    console.log(response.data);
  })
  .catch((error) => {
    // 处理请求错误
    console.error(error.response?.data || error.message);
  });

响应示例 ​

json
{
  "version": "0.1.20210917",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0890 sec.",
  "cost": 0.05,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0100 sec.",
      "cost": 0.05,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "google_ads",
        "search_volume",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "search_volume",
        "se": "google_ads",
        "location_name": "United States",
        "keywords": [
          "buy laptop",
          "cheap laptops for sale",
          "purchase laptop"
        ]
      },
      "result": null
    }
  ]
}

错误处理 ​

  • status_code 为 20000 表示请求成功。
  • 单次提交 100 个任务时，出部分返回 40006。
  • 应用端应同时检查请求级 status_code、任务级 status_code 及对应的 status_message。
  • 完整错误码可参考 /v3/appendix/errors。

实用场景 ​

  • 评估需求规模：批量获取目标词的搜索量和月度趋势，为 SEO优级和选题规划提供依据。
  • 筛选高价值：结合搜索量、竞争指数及首页顶部出价区间，识别适合自然排名或付费投放的。
  • 比较不同地区市场：按位置名称、位置代码或坐标提交任务，对比各地区需求，支持本地 SEO 和区域市场决策。
  • 分析历史搜索趋势：指定最长 4 年的日期范围，评估季节性和长期变化，更新与营销预算安排。
  • 监控任务结果：通过 postback_url 或 pingback_url 接收异步通知，自动将搜索量数据同步到库或报表系统。

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

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