数据 / 点击流数据 / 本平台 Search Volume（实时）

接口说明

该接口用于实时获取搜索量数据。单次请求最多可提交 1000 个，返回的搜索量会基于以下两类数据源之一进行归一化计算：

• 点击流数据
• Bing 搜索量数据

接口路径：

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

计费说明

该接口按请求次数计费，无论 keywords 数组中 1 个还是 1000 个，一次请求只计费一次。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

根据原文示例返回的 cost: 0.15（USD），可折算为：

参考价约 ¥2.4000 / 次

注意：这是示例响应中的费用，不代表固定单价。

频率限制

• 默认最高可达 2000 次 API 调用/分钟
• 但由于平台限制，每个账户每分钟最多只能发送 12 次该接口请求
• 单次请求的 keywords 数组最多支持 1000 个

请求格式

所有 POST 数据使用 JSON UTF-8 编码，并采用数组形式创建任务：

[
 {
 "keywords": ["youtube", "you tube", "youtub"],
 "location_code": 2840,
 "language_name": "English",
 "use_clickstream": true,
 "tag": "test-tag"
 }
]

---

请求参数

以下是设置任务时可用的字段说明。

字段名	类型	说明
keywords	array	目标数组。填。UTF-8 编码；最多 1000 个；会被转换为小写。注意：某些符号和字符（如部分 UTF 符号、emoji）不被支持。
location_name	string	搜索引擎地域完整名称。当未指定 location_code 时填。可通过 /v3/keywords_data/clickstream_data/locations_and_languages 获取可用地域列表。示例：United Kingdom
location_code	integer	搜索引擎地域编码。当未指定 location_name 时填。可通过 /v3/keywords_data/clickstream_data/locations_and_languages 获取可用地域编码。示例：2826
language_name	string	搜索引擎语言完整名称。当未指定 language_code 时填。可通过 /v3/keywords_data/clickstream_data/locations_and_languages 获取可用语言列表。示例：English
language_code	string	搜索引擎语言编码。当未指定 language_name 时填。可通过 /v3/keywords_data/clickstream_data/locations_and_languages 获取可用语言编码。示例：en
use_clickstream	boolean	是否使用点击流数据作为结果来源。可选。true：基于点击流数据返回搜索量；false：使用 Bing 搜索量数据计算。默认值：true。**注意：**只有 Bing 支持的地域才能在设为 false 时使用 Bing 数据；地域即使设为 false，仍会基于点击流数据计算。
tag	string	自定义任务标识。可选，最大 255 个字符。可用于请求与响应结果匹；该值会原样出现在响应的 data 对象中。

---

返回结果说明

接口返回 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，详见 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	当前请求的 URL 路径
data	array / object	与请求体中提交的参数一致
result	array	结果数组

result字段

字段名	类型	说明
location_code	integer	请求中的地域编码；若无数据则为 null
language_code	string	请求中的语言编码；若无数据则为 null
items_count	string	items 数组中的结果数量
items	array	结果数组

注意：如果请求中的存在拼写错误，接口可能返回拼写修正后的数据。平台会借助 Google Ads API 的拼写校验能力进行检查与验证。

items字段

字段名	类型	说明
keyword	string	请求中提交的
use_clickstream	boolean	是否启用了 use_clickstream 参数，可选值：true、false
search_volume	integer	当前搜索量
monthly_searches	array	月度搜索量数组
year	integer	年份（出现在 monthly_searches 的对象中）
month	integer	月份（出现在 monthly_searches 的对象中）
search_volume	integer	对应年月的搜索量（出现在 monthly_searches 的对象中）

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/clickstream_data/dataforseo_search_volume/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keywords": ["you tube", "youtube", "youtub"],
 "location_name": "United States",
 "language_name": "English",
 "use_clickstream": true,
 "tag": "test-tag"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/clickstream_data/dataforseo_search_volume/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "keywords": ["you tube", "youtube", "youtub"],
 "location_name": "United States",
 "language_name": "English",
 "use_clickstream": True,
 "tag": "test-tag"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript

const url = "https://api.seermartech.cn/v3/keywords_data/clickstream_data/dataforseo_search_volume/live";

const payload = [
 {
 keywords: ["you tube", "youtube", "youtub"],
 location_name: "United States",
 language_name: "English",
 use_clickstream: true,
 tag: "test-tag"
 }
];

fetch(url, {
 method: "POST",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 body: JSON.stringify(payload)
})
 .then(res => res.json)
 .then(data => console.log(data))
 .catch(err => console.error(err));

---

响应示例

{
 "version": "0.1.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.6964 sec.",
 "cost": 0.15,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "dataforseo_search_volume",
 "se": "clickstream_data",
 "location_code": 2840,
 "language_code": "en",
 "use_clickstream": true,
 "tag": "test-tag",
 "keywords": ["you tube", "youtube", "youtub"]
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": "en",
 "items_count": 3,
 "items": [
 {
 "keyword": "you tube",
 "use_clickstream": true,
 "search_volume": 141457261,
 "monthly_searches": []
 },
 {
 "keyword": "youtube",
 "use_clickstream": true,
 "search_volume": 141457261,
 "monthly_searches": []
 },
 {
 "keyword": "youtub",
 "use_clickstream": true,
 "search_volume": 401067,
 "monthly_searches": []
 }
 ]
 }
 ]
 }
 ]
}

---

状态码与异常处理

• 顶层 status_code 表示整个请求的处理结果
• tasks[].status_code 表示单个任务的处理结果
• 建议同时检查：
• 顶层 status_code
• tasks_error
• 每个任务的 status_code

完整错误码与状态信息请参考：

• /v3/appendix/errors

---

使用建议

1. 优批量提交：该接口按请求计费，因此尽量将放同一个请求中，以提升成本效率。
2. 地域与语言成对校验：请求前通过 /v3/keywords_data/clickstream_data/locations_and_languages 获取支持的地域和语言，参数无效。
3. 按数据源理解结果差异：

• use_clickstream=true：更适合依赖点击流估算的场景
• use_clickstream=false：适用于 Bing 覆盖地域，但不保证所有地域都能真正走 Bing 数据

4. 处理拼写归一化：如果存在拼写偏差，返回结果可能基于修正后的词，建议在后处理逻辑中保留原词与返回词映射。

实用场景

• 批量评估需求规模：一次提交最多 1000 个词，快速获取搜索量， SEO 选词和优级排序。
• 对比近似拼写词流量差异：如品牌词、错拼词、口语化写法，识别是否需要单独布局页面或投放。
• 验证不同地区的搜索热度：结合 location_code 与 language_code 查询本地化搜索量，支持 SEO 市场判断。
• 构建分层库：基于 search_volume 和 monthly_searches 对进行头部词、部词、长尾词划分，提高规划效率。
• 校验点击流与 Bing 口径差异：通过切换 use_clickstream，比较不同数据来源下的搜索量结果，为模型选用更合适的数据口径。