SeerMarTech API 文档

主题

按任务 ID 获取 Google 类目结果 ​

本接口使用 GET 方法，通过任务 ID 获取类目任务结果：

GET https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_get/$id

> 该接口属于历史版本的 Google AdWords 数据能力，建议新项目优迁移至 Google Ads API 接口。

本接口根据指定的产品或服务类目返回建议，并提供以下数据：

  • 最近一个月的搜索量
  • 最近 12 个月的搜索量趋势
  • 当前平均每次点击费用（CPC）
  • 付费搜索竞争程度
  • 所属的产品和服务类目

单次任务最多可返回 700 个及完整数据。

计费说明 ​

本接口对提交任务进行计费，获取任务结果不会重复计费。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

路径参数 ​

参数类型填说明
idstring是任务唯一标识，UUID 格式。任务提交成功后，可在 30 天使用该 ID 获取任务结果。

请求示例 ​

cURL ​

bash
task_id="02031629-0696-0109-0000-4aa9592ce749"

curl --location --request GET \
  "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_get/${task_id}" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

TypeScript ​

typescript
import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios
  .get(
    `https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_get/${taskId}`,
    {
      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);
  });

Python ​

python
import requests

task_id = "02031629-0696-0109-0000-4aa9592ce749"

response = requests.get(
    f"https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_get/{task_id}",
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
)

if response.ok:
    print(response.json())
else:
    print(f"请求失败：{response.status_code} {response.text}")

PHP ​

php
<?php

$taskId = '02031629-0696-0109-0000-4aa9592ce749';
$url = 'https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_get/' . $taskId;

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new Exception(curl_error($ch));
}

curl_close($ch);

echo $response;

C# ​

csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    public static async Task Main()
    {
        var taskId = "02031629-0696-0109-0000-4aa9592ce749";
        var url =
            $"https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_get/{taskId}";

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "smt_live_YOUR_KEY");

        var response = await client.GetAsync(url);
        var content = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            Console.WriteLine(content);
        }
        else
        {
            Console.WriteLine($"请求失败：{(int)response.StatusCode} {content}");
        }
    }
}

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组。每个任务对象任务状态、请求参数和结果数据。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求级状态码。完整状态码列表请参考错误码文档。
status_messagestring请求级提示信息。
timestring接口执行耗时，单位为秒。
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 数组中的结果数量。
patharray请求路径信息。
dataobject提交任务时使用的参数。
resultarray结果数组。

data 字段 ​

data 通常提交任务时的原始参数，例如：

字段类型说明
apistring数据接口名称。
functionstring接口功能名称。
sestring搜索引擎名称。
location_namestring地理位置名称。
language_namestring语言名称。
category_codeinteger产品或服务类目编码。
tagstring用户自定义任务标签。

result 结果字段 ​

字段类型说明
keywordstring返回的。
location_codeinteger | null地理位置编码。如果没有对应数据，则为 null。
language_codestring | null语言编码。如果没有对应数据，则为 null。
search_partnersboolean是否合作伙伴网络中的数据。
competitionfloat | null付费搜索竞争程度，取值范围为 0 至 1，数值越高表示竞争越激烈。如果没有数据，则为 null。
cpcfloat | null平均每次点击费用。该值表示历史平均 CPC，单位为人民币。如果没有数据，则为 null。
search_volumeinteger | null月均搜索量，为指定地理位置下的估算值。如果没有数据，则为 null。
categoriesarray | null对应的产品和服务类目。如果没有数据，则为 null。
monthly_searchesarray | null最近 12 个月的月度搜索量。如果没有数据，则为 null。

monthly_searches 数组字段 ​

字段类型说明
yearinteger年份。
monthinteger月份，取值为 1 至 12。
search_volumeinteger该月份的估算搜索量。

响应示例 ​

json
{
  "version": "0.1.20200130",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "5.2880 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02031629-0696-0109-0000-4aa9592ce749",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "5.1000 sec.",
      "cost": 0,
      "result_count": 3,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "keywords_for_category",
        "task_get"
      ],
      "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.0013572539,
          "cpc": 0,
          "search_volume": 6600,
          "categories": [],
          "monthly_searches": [
            {
              "year": 2023,
              "month": 12,
              "search_volume": 6600
            }
          ]
        },
        {
          "keyword": "mountain bike",
          "location_code": 1006886,
          "language_code": "en",
          "search_partners": false,
          "competition": 0.9998855923,
          "cpc": 0.770228,
          "search_volume": 5400,
          "categories": [],
          "monthly_searches": [
            {
              "year": 2023,
              "month": 12,
              "search_volume": 5400
            }
          ]
        },
        {
          "keyword": "hyundai kona",
          "location_code": 1006886,
          "language_code": "en",
          "search_partners": false,
          "competition": 0.2902896883,
          "cpc": 0.860399,
          "search_volume": 4400,
          "categories": [],
          "monthly_searches": [
            {
              "year": 2023,
              "month": 12,
              "search_volume": 4400
            }
          ]
        }
      ]
    }
  ]
}

错误处理 ​

建议客户端同时检查以下状态字段：

  • 顶层 status_code：判断本次 API 请求是否成功。
  • 任务级 tasks[].status_code：判断单个任务是否成功。
  • status_message：获取错误或状态说明。
  • result：任务成功时通常结果数据；任务失败或无数据时，可能为空或为 null。

当 tasks_error 大于 0，或任务级状态码表示错误时，应记录任务 ID 和错误信息，并根据业务需要执行重试或人工排查。

实用场景 ​

  • 挖掘类目：根据产品或服务类目批量获取，为 SEO规划和站点信息架构提供数据依据。
  • 筛选高潜力词：结合搜索量、竞争程度和 CPC 评估价值，优更商业潜力的词组。
  • 分析季节趋势：使用最近 12 个月的月度搜索量识别季节性需求，优化发布时间和广告预算分。
  • 构建库：按地区、语言和类目整理结果，为多国家、多语言 SEO 项目建立基础词库。
  • 评估付费搜索机会：对比的 CPC 与竞争程度，制定搜索广告投放和自然流量获取策略。

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

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