点击流搜索量（实时）

接口说明

该接口用于通过一次实时请求，批量获取最多 1000 个的基于点击流的搜索量数据，并返回这些在各可用国家/地区的搜索量分布。

接口路径：

POST /v3/keywords_data/clickstream_data/global_search_volume/live

完整请求地址：

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

与传统按国家维度查询不同，本接口直接返回的月均搜索量估算值，并附带 country_distribution 字段，便于分析不同国家对搜索需求的贡献占比。

计费与频率限制

• 每次请求都会产生费用
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 响应中的 cost 为平台 API 返回的金额
• 请求频率上限：2000 次/分钟
• 最大并发请求数：30

请求格式

所有 POST 数据均需使用 JSON（UTF-8 编码）提交。

请求体为 JSON 数组，格式如下：

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

请求参数

任务对象字段

字段名	类型	填	说明
keywords	array	是	目标数组。最多可提交 1000 个；每个长度至少 3 个字符；系统会自动转为小写；需使用 UTF-8 编码。注意：部分特殊符号、UTF 特殊字符、emoji 等不被支持。
tag	string	否	自定义任务标识，用于请求结果匹。最长 255 个字符。响应中会在 data 对象原样返回。

keywords 字段限制

• 单次请求最多 1000 个
• 每个至少 3 个字符
• 会被自动转换为小写
• 不支持部分特殊符号、非常规 UTF 字符及 emoji
• 建议在提交前完成洗，因字符不合规导致任务报错或结果异常

返回结果说明

接口返回 JSON 对象，顶层 tasks 数组。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表参考 /v3/appendix/errors
status_message	string	通用状态信息
time	string	接口执行耗时，单位秒
cost	float	本次请求总费用（USD）
tasks_count	integer	tasks 数组中的任务数
tasks_error	integer	返回错误的任务数
tasks	array	任务结果数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态说明
time	string	任务执行耗时
cost	float	当前任务费用（USD）
result_count	integer	result 数组中的结果数
path	array	请求路径拆分结果
data	object	请求时提交的参数回显
result	array	结果数组

result[] 字段

字段名	类型	说明
items_count	integer	items 数组中的结果条数
items	array	结果列表

items[] 字段

字段名	类型	说明
keyword	string	。返回时会进行解码，例如 %## 会被还原，+ 会被解码为空格。
search_volume	integer	基于点击流估算的月均搜索量
country_distribution	array	在各国家/地区的点击流搜索量分布，以及占搜索量的比例

country_distribution[] 字段

字段名	类型	说明
country_iso_code	string	国家 ISO 代码
search_volume	integer	该国家/地区的搜索量
percentage	float	占搜索量的比例

状态码与错误处理

请重点以下字段：

• 顶层 status_code
• tasks[].status_code
• tasks_error

建议在接时建立统一的异常处理机制，覆盖以下：

• 请求参数错误
• 任务级部分失败
• 并发或频率限制触发
• 空结果或字段缺失
• 接口异常

完整错误码列表可参考容路径：

/v3/appendix/errors

请求示例

cURL

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-raw '[
 {
 "tag": "test-tag",
 "keywords": [
 "you tube",
 "youtube",
 "youtub"
 ]
 }
]'

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"
}
payload = [
 {
 "tag": "test-tag",
 "keywords": [
 "you tube",
 "youtube",
 "youtub"
 ]
 }
]

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

if result.get("status_code") == 20000:
 print(result)
else:
 print(f'error. Code: {result.get("status_code")} Message: {result.get("status_message")}')

TypeScript

import axios from "axios";

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

axios({
 method: "post",
 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",
 },
 data: postArray,
})
 .then((response) => {
 // 返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.log(error);
 });

响应示例

{
 "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": "8c5b7f2e-6f4b-4c5d-9f5e-1a2b3c4d5e6f",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.8421 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": "youtube",
 "search_volume": 257466342,
 "country_distribution": [
 {
 "country_iso_code": "US",
 "search_volume": 84500000,
 "percentage": 32.82
 },
 {
 "country_iso_code": "IN",
 "search_volume": 42100000,
 "percentage": 16.35
 }
 ]
 },
 {
 "keyword": "you tube",
 "search_volume": 18575928,
 "country_distribution": [
 {
 "country_iso_code": "US",
 "search_volume": 6100000,
 "percentage": 32.84
 }
 ]
 },
 {
 "keyword": "youtub",
 "search_volume": 2081434,
 "country_distribution": [
 {
 "country_iso_code": "US",
 "search_volume": 690000,
 "percentage": 33.15
 }
 ]
 }
 ]
 }
 ]
 }
 ]
}

响应解读

以上示例表示：

• 请求成功，顶层 status_code 为 20000
• 本次请求处理 1 个任务
• 返回了 3 个的点击流搜索量
• youtube 的月均搜索量约为 257466342
• country_distribution 显示了不同国家对搜索量的贡献比例，可用于市场分析

使用建议

• 如果需要评估在范围的真实需求强弱，可优 search_volume
• 如果需要判断重点国家市场，可结合 country_distribution[].percentage
• 建议将拼写变体、品牌词、通用词一起提交，便于做需求对比
• 对于 SEO、出海选题、多市场投放评估，这一接口适合用作前置筛选数据源

实用场景

• 筛选高需求：批量比较多个候选词的搜索量，优选择需求更高的主题做或落地页。
• 识别重点国家市场：查看 country_distribution 中各国占比，判断某个主要需求来自哪些国家，为化 SEO 提供依据。
• 对比品牌词与拼写变体：同时提交品牌标准词、空格变体、拼写错误词，评估真实搜索需求差异，优化品牌词覆盖策略。
• 验证出海选题优级：在生产前确认是否备足够需求，减少低价值选题。
• 多国家投放规划：根据搜索量与国家分布，判断哪些市场值得优投放广告或布局本地化页面。