SeerMarTech API 文档

主题

keywords_data/clickstream_data/dataforseo_search_volume/live ​

POST /v3/keywords_data/clickstream_data/dataforseo_search_volume/live

接口说明 ​

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

本接口用于实时获取搜索量数据。搜索量可基于 Bing 搜索量数据或点击流数据进行归一化处理。单次请求最多提交 1000 个，并返回每个的当前搜索量及月度搜索量历史。

请求体使用 UTF-8 编码的 JSON 数组格式：

json
[
  {
    "keywords": ["youtube", "视频平台"],
    "location_name": "United States",
    "language_name": "English"
  }
]

每个 Live API 请求只能一个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准，但受系统及数据源限制，单个账户每分钟最多可发送 12 次请求。

无论一次请求 1 个还是 1000 个，均按请求计费，而不是按数量计费。

计费说明 ​

  • 参考价约 ¥1.08 / 次（按原始示例中的 0.15 美等值换算供参考）。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • 当请求中多个时，只要请求成功提交，仍按一次请求计费。

请求参数 ​

参数类型填说明
keywordsarray是目标数组。使用 UTF-8 编码，最多 1000 个。系统会将转换为小写格式。部分特殊符号、Unicode 字符或表符号可能不被支持。
location_namestring条件填搜索引擎地域的完整名称。未提供 location_code 时填写。示例：United Kingdom。
location_codeinteger条件填搜索引擎地域代码。未提供 location_name 时填写。示例：2826。
language_namestring条件填搜索引擎语言的完整名称。未提供 language_code 时填写。示例：English。
language_codestring条件填搜索引擎语言代码。未提供 language_name 时填写。示例：en。
use_clickstreamboolean否是否使用点击流数据计算搜索量。true：使用点击流数据；false：使用 Bing 搜索量数据。默认值为 true。
tagstring否用户自定义任务标识，用于请求与响应结果。最大长度为 255 个字符。指定的值会原样返回在响应的 data 对象中。

地域和语言 ​

可通过以下接口获取可用的地域及语言列表：

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

location_name 与 location_code 至少填写一个；language_name 与 language_code 至少填写一个。

use_clickstream 的计算规则 ​

  • true：返回基于点击流数据计算的搜索量。
  • false：优使用 Bing 搜索量数据计算搜索量。
  • Bing 搜索量适用于 Bing 搜索量历史地域列表及 Bing Ads 地域列表中的地域。
  • 对于地域，即使将 use_clickstream 设置为 false，系统仍会使用点击流数据计算搜索量。

请求示例 ​

cURL ​

bash
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 ​

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",
}

payload = [
    {
        "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=payload, timeout=60)
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
const response = await fetch(
  "https://api.seermartech.cn/v3/keywords_data/clickstream_data/dataforseo_search_volume/live",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify([
      {
        keywords: ["you tube", "youtube", "youtub"],
        location_name: "United States",
        language_name: "English",
        use_clickstream: true,
        tag: "test-tag",
      },
    ]),
  }
);

const result = await response.json();

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(
    `请求失败，错误码：${result.status_code}，错误信息：${result.status_message}`
  );
}

响应结构 ​

接口返回 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 字段 ​

字段类型说明
location_codeinteger请求中使用的地域代码。无数据时为 null。
language_codestring请求中使用的语言代码。无数据时为 null。
items_countintegeritems 数组中的结果数量。
itemsarray搜索量结果数组。

items 字段 ​

字段类型说明
keywordstring请求中提交的。对于拼写疑似错误的，系统可能返回纠正后的数据。
use_clickstreamboolean表示本次结果使用的数据来源。true 表示点击流数据，false 表示 Bing 搜索量数据。
search_volumeinteger当前搜索量。
monthly_searchesarray按月份返回的搜索量历史记录。

monthly_searches 字段 ​

字段类型说明
yearinteger年份。
monthinteger月份，取值范围为 1 至 12。
search_volumeinteger指定月份的搜索量。

> 如果请求中的存在拼写错误，系统可能依据校验结果返回正确拼写对应的数据。因此，建议使用响应中的 keyword 字段作为最终匹。

响应示例 ​

json
{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "3.6964 sec.",
  "cost": 0.15,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "060815 ಸಮಾಜ-0001-0000-0000-000000000001",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "3.5000 sec.",
      "cost": 0.15,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "clickstream_data",
        "dataforseo_search_volume",
        "live"
      ],
      "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": 123456,
              "monthly_searches": [
                {
                  "year": 2024,
                  "month": 7,
                  "search_volume": 120000
                }
              ]
            },
            {
              "keyword": "youtube",
              "use_clickstream": true,
              "search_volume": 141457261,
              "monthly_searches": [
                {
                  "year": 2024,
                  "month": 7,
                  "search_volume": 140000000
                }
              ]
            },
            {
              "keyword": "youtub",
              "use_clickstream": true,
              "search_volume": 401067,
              "monthly_searches": [
                {
                  "year": 2024,
                  "month": 7,
                  "search_volume": 395000
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理 ​

建议客户端根据顶层 status_code 及任务级 status_code 分别处理请求结果：

  • 20000：请求或任务处理成功。
  • 状态码：请求或任务处理失败，应结合 status_message 定位原因。
  • 当 tasks_error 大于 0 时，应逐项检查 tasks 数组中的任务状态。

实用场景 ​

  • 批量评估搜索需求：一次提交最多 1000 个，快速获取当前搜索量，支持 SEO 选词和优级排序。
  • 比较不同地域的潜力：针对多个地域分别查询相同，识别目标市场的搜索需求差异，化 SEO 布局。
  • 分析搜索趋势：读取 monthly_searches 历史数据，识别季节性波动和长期增长趋势，指导发布计划。
  • 校验拼写与搜索价值：利用响应中的标准化 keyword 及搜索量结果，发现拼写错误或低价值，提升库质量。
  • 对比点击流与搜索引擎数据：切换 use_clickstream 参数，比较不同数据来源下的搜索量结果，为流量预测和市场规模评估提供依据。

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

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