SeerMarTech API 文档

主题

Clickstream Global Search Volume 实时查询 ​

POST /v3/keywords_data/clickstream_data/global_search_volume/live

本接口使用 POST 方法，请求路径为：

/v3/keywords_data/clickstream_data/global_search_volume/live

本接口用于实时获取的点击流搜索量数据。单次请求最多支持 1000 个，并返回各可用国家或地区的搜索量分布及占搜索量的比例。

接口信息 ​

  • 请求方法：POST
  • 请求地址：https://api.seermartech.cn/v3/keywords_data/clickstream_data/global_search_volume/live
  • Content-Type：application/json
  • 请求体格式：JSON 数组
  • 单次请求任务数：1
  • 每分钟最大 API 调用数：以认证说明中的 30/60/120 次/分钟规则为准
  • 最大并发请求数：30

所有请求参数放在通用请求数组中，例如：

json
[
  {
    "keywords": [
      "you tube",
      "youtube",
      "youtub"
    ],
    "tag": "test-tag"
  }
]

计费说明 ​

本接口按请求计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

参数类型填说明
keywordsarray是目标数组。使用 UTF-8 编码，最多 1000 个。每个至少 3 个字符。平台会将转换为小写格式。部分符号和字符不受支持，例如部分 Unicode 字符和表符号。
tagstring否用户自定义任务标识，用于匹请求与响应结果。最大长度为 255 个字符。提交的值会原样返回在响应的 data 对象中。

keywords 参数限制 ​

  • 最多提交 1000 个。
  • 每个至少 3 个字符。
  • 会自动转换为小写。
  • 不支持部分特殊符号、Unicode 字符和表符号。
  • 建议在提交前完成洗、去重和长度校验。

响应结构 ​

服务端返回 JSON 数据 tasks 数组。

顶层响应字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求级状态码。20000 表示请求成功。
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当前请求的 URL 路径信息。
dataobject请求中提交的参数。
resultarray搜索量结果数组。

result 与 items 字段 ​

字段类型说明
items_countintegeritems 数组中的结果数量。
itemsarray含及搜索量数据。
keywordstring。经过 URL 编码的会被解码，+ 会被解码为空格。
search_volumeinteger基于点击流数据估算的月均搜索量，表示该的大致搜索次数。
country_distributionarray按国家或地区划分的点击流搜索量分布。
country_iso_codestring国家或地区的 ISO 代码。
search_volumeinteger该国家或地区的搜索量。
percentagefloat该国家或地区搜索量占搜索量的比例。

country_distribution 位于每个结果对象中结构如下：

json
{
  "country_iso_code": "US",
  "search_volume": 123456,
  "percentage": 12.34
}

请求示例 ​

cURL ​

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

Python ​

python
import requests

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

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

post_data = [
    {
        "tag": "test-tag",
        "keywords": [
            "you tube",
            "youtube",
            "youtub",
        ],
    }
]

response = requests.post(url, headers=headers, json=post_data)
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 = [
  {
    tag: "test-tag",
    keywords: ["you tube", "youtube", "youtub"],
  },
];

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

PHP ​

php
<?php

$url = 'https://api.seermartech.cn/v3/keywords_data/clickstream_data/global_search_volume/live';

$postData = [
    [
        'tag' => 'test-tag',
        'keywords' => [
            'you tube',
            'youtube',
            'youtub'
        ]
    ]
];

$ch = curl_init($url);

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

$response = curl_exec($ch);

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

curl_close($ch);

$result = json_decode($response, true);

if (($result['status_code'] ?? null) === 20000) {
    print_r($result);
} else {
    echo '请求失败。状态码：'
        . ($result['status_code'] ?? '未知')
        . '，消息：'
        . ($result['status_message'] ?? '未知');
}

响应示例 ​

json
{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.8803 sec.",
  "cost": 0.15,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "7f8c1f2a-8f0e-4a1b-9b22-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.8501 sec.",
      "cost": 0.15,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "clickstream_data",
        "global_search_volume",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "global_search_volume",
        "se": "clickstream_data",
        "tag": "test-tag",
        "keywords": [
          "you tube",
          "youtube",
          "youtub"
        ]
      },
      "result": [
        {
          "items_count": 3,
          "items": [
            {
              "keyword": "you tube",
              "search_volume": 18575928,
              "country_distribution": [
                {
                  "country_iso_code": "US",
                  "search_volume": 1234567,
                  "percentage": 6.64
                }
              ]
            },
            {
              "keyword": "youtube",
              "search_volume": 18575928,
              "country_distribution": [
                {
                  "country_iso_code": "US",
                  "search_volume": 1234567,
                  "percentage": 6.64
                }
              ]
            },
            {
              "keyword": "youtub",
              "search_volume": 2081434,
              "country_distribution": [
                {
                  "country_iso_code": "US",
                  "search_volume": 234567,
                  "percentage": 11.27
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理 ​

  • status_code 既可能出现在顶层响应，也可能出现在单个任务对象中。
  • 20000 表示请求或任务处理成功。
  • 应同时检查顶层 status_code、tasks_error 以及每个任务的 status_code。
  • 当部分任务失败时，应根据对应任务的 status_message 记录并处理异常。
  • 生产环境建议实现重试、时、限流和错误日志机制。

实用场景 ​

  • 评估需求：对目标获取月均搜索量，帮助制定 SEO优级。
  • 识别重点市场：分析 country_distribution，定位搜索需求集中的国家或地区，支持市场和本地化决策。
  • 规划多地区：比较同一在不同国家的搜索量占比，为语言版本、地区页面和本地布局提供依据。
  • 筛选高潜力：批量提交最多 1000 个，根据点击流搜索量快速建立优级单。
  • 校验变体价值：对拼写变体、品牌词和长尾词进行搜索量对比，确定页面标题、主题和链接策略。

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

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