SeerMarTech API 文档

主题

keywords_data/clickstream_data/bulk_search_volume/live ​

POST /v3/keywords_data/clickstream_data/bulk_search_volume/live

实时设置批量点击流搜索量任务 ​

POST https://api.seermartech.cn/v3/keywords_data/clickstream_data/bulk_search_volume/live

本接口用于一次实时请求查询最多 1000 个的点击流搜索量数据，并可返回最近最多 12 个月的历史搜索量。可用历史数据范围取决于、地区和语言等参数。

所有 POST 请求体使用 UTF-8 编码的 JSON 格式，并以 JSON 数组提交任务：

json
[
  {
    "keywords": [""],
    "location_name": "地区名称"
  }
]

调用限制如下：

  • 每次 Live 请求只能 1 个任务。
  • 每个任务最多提交 1000 个。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 同时执行的请求数最多为 30 个。
  • 每次请求均会产生费用。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

参数类型说明
keywordsarray填。 目标列表。<br><br>使用 UTF-8 编码；最多 1000 个；每个至少 3 个字符；平台会将转换为小写格式。<br><br>部分符号和字符不可用，例如特殊 Unicode 字符和表符号。
location_namestring地区完整名称。<br><br>如果未指定 location_code，则填。location_name 与 location_code 至少指定一个。<br><br>示例：United Kingdom
location_codeinteger地区代码。<br><br>如果未指定 location_name，则填。location_name 与 location_code 至少指定一个。<br><br>示例：2840
tagstring用户自定义任务标识，可选。<br><br>最大长度为 255 个字符。可使用该字段识别任务，并在结果中匹对应数据。提交的 tag 值会原样返回在响应任务的 data 对象中。

可通过以下接口获取支持的地区及名称、代码：

GET https://api.seermartech.cn/v3/keywords_data/clickstream_data/locations_and_languages

返回结果 ​

接口返回 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与 POST 请求中提交的参数基本一致。
resultarray查询结果数组。

result 结果字段 ​

字段类型说明
location_codeinteger请求中指定的地区代码。
items_countintegeritems 数组中的结果数量。
itemsarray含及搜索量数据。

items 数据字段 ​

字段类型说明
keywordstring。返回时会对经过编码的进行解码；字符 + 会被解码为空格。
search_volumeinteger基于点击流数据计算的平均月搜索量，表示指定的大致搜索次数。
monthly_searchesarray最近最多 12 个月的月度搜索量数据，按指定地区统计。

monthly_searches 字段 ​

字段类型说明
yearinteger年份。
monthinteger月份，取值为 1 至 12。
search_volumeinteger当月平均搜索量。

请求示例 ​

curl ​

bash
curl --location 'https://api.seermartech.cn/v3/keywords_data/clickstream_data/bulk_search_volume/live' \
  --header 'Authorization: Bearer smt_live_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "location_name": "United States",
      "keywords": [
        "you tube",
        "youtube",
        "youtub"
      ]
    }
  ]'

PHP ​

php
<?php

$apiUrl = 'https://api.seermartech.cn';
$apiKey = 'smt_live_YOUR_KEY';

$postData = [
    [
        'location_name' => 'United States',
        'keywords' => [
            'you tube',
            'youtube',
            'youtub'
        ]
    ]
];

$ch = curl_init($apiUrl . '/v3/keywords_data/clickstream_data/bulk_search_volume/live');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($postData, JSON_UNESCAPED_UNICODE)
]);

$response = curl_exec($ch);

if ($response === false) {
    echo '请求失败：' . curl_error($ch);
} else {
    $result = json_decode($response, true);
    print_r($result);
}

curl_close($ch);

TypeScript ​

typescript
import axios from "axios";

const postData = [
  {
    location_code: 2840,
    tag: "test-tag",
    keywords: [
      "you tube",
      "youtube",
      "youtub",
    ],
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/clickstream_data/bulk_search_volume/live",
    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);
  });

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/clickstream_data/bulk_search_volume/live"

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

post_data = [
    {
        "location_name": "United States",
        "keywords": [
            "you tube",
            "youtube",
            "youtub",
        ],
    }
]

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

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

C# ​

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

public class ClickstreamSearchVolumeDemo
{
    public static async Task Main()
    {
        using var httpClient = new HttpClient();

        httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "smt_live_YOUR_KEY");

        var postData = new[]
        {
            new
            {
                location_name = "United States",
                keywords = new[]
                {
                    "you tube",
                    "youtube",
                    "youtub"
                }
            }
        };

        var json = JsonSerializer.Serialize(postData);
        using var content = new StringContent(
            json,
            Encoding.UTF8,
            "application/json"
        );

        var response = await httpClient.PostAsync(
            "https://api.seermartech.cn/v3/keywords_data/clickstream_data/bulk_search_volume/live",
            content
        );

        var result = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            // 处理返回结果
            Console.WriteLine(result);
        }
        else
        {
            Console.WriteLine(
                $"请求失败：HTTP {(int)response.StatusCode} {response.ReasonPhrase}"
            );
            Console.WriteLine(result);
        }
    }
}

响应示例 ​

json
{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.3889 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1234 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "clickstream_data",
        "bulk_search_volume",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "bulk_search_volume",
        "se": "clickstream_data",
        "location_name": "United States",
        "location_code": 2840,
        "tag": "test-tag",
        "keywords": [
          "you tube",
          "youtube",
          "youtub"
        ]
      },
      "result": [
        {
          "location_code": 2840,
          "items_count": 3,
          "items": [
            {
              "keyword": "you tube",
              "search_volume": 3986664,
              "monthly_searches": [
                {
                  "year": 2024,
                  "month": 7,
                  "search_volume": 3600000
                }
              ]
            },
            {
              "keyword": "youtube",
              "search_volume": 157924192,
              "monthly_searches": [
                {
                  "year": 2024,
                  "month": 7,
                  "search_volume": 150000000
                }
              ]
            },
            {
              "keyword": "youtub",
              "search_volume": 123456,
              "monthly_searches": [
                {
                  "year": 2024,
                  "month": 7,
                  "search_volume": 120000
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

错误处理 ​

请根据顶层 status_code、任务级 status_code 以及对应的 status_message 判断请求和任务是否成功。建议在业务系统中处理以下：

  • HTTP 请求失败或时。
  • 顶层 status_code 非成功状态。
  • tasks_error 大于 0。
  • 单个任务的 status_code 非成功状态。
  • result 为空或结果数量少于提交数量。

完整错误码请参考错误码说明。

实用场景 ​

  • 批量评估需求：一次提交最多 1000 个，快速获取平均月搜索量，为筛选和优级排序提供依据。
  • 分析季节性变化：读取最近最多 12 个月的 monthly_searches 数据，识别季节性需求高峰，优化发布和广告投放时间。
  • 比较不同地区的搜索需求：通过 location_name 或 location_code 分地区查询相同，制定本地化 SEO和市场策略。
  • 校验扩展结果：批量查询词根、拼写变体和长尾词的点击流搜索量，过滤低需求词并发现潜在流量机会。
  • 构建搜索需求监测报表：结合 tag 标记不同项目或批次，定期保存查询结果，跟踪搜索需求的历史变化。

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

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