keywords_data/bing/search_volume/live

POST /v3/keywords_data/bing/search_volume/live

接口说明

POST /v3/keywords_data/bing/search_volume/live

本接口实时返回 Bing 搜索量数据最近一个月的搜索量、最长可追溯 24 个月的搜索趋势、平均每次点击费用（CPC）和付费搜索竞争度。

Live 接口会在同一次请求中直接返回结果，无需像 Standard 接口一样分别提交任务和查询结果。如果不要求实时获取数据，可使用 Standard 方式提交任务并异步获取结果，费用通常更低。

历史数据最长支持 24 个月。每次请求最多提交 1000 个，数量不会影响单次请求价格。

请求格式：JSON（UTF-8）
单次 Live 请求支持 1 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准
每个最多 100 个字符
返回结果会按分别放在 result 数组中
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
参考价约 ¥0.5400 / 次（示例任务费用，价格以响应头为准）

请求参数

请求体是 JSON 数组，格式为 [{ ... }]。

参数	类型	填	说明
`keywords`	array	是	要查询的列表。最多 1000 个，每个最多 100 个字符。系统会将转换为小写，并在结果中分别返回。
`location_name`	string	条件填	搜索引擎位置的完整名称。未指定 `location_code` 或 `location_coordinate` 时填。使用此参数后，无需再传另外两个位置参数。示例：`London,England,United Kingdom`。
`location_code`	integer	条件填	搜索引擎位置编码。未指定 `location_name` 或 `location_coordinate` 时填。示例：`2840`。
`location_coordinate`	string	条件填	地理坐标，格式为 `纬度,经度`，例如 `52.6178549,-155.352142`。返回数据对应坐标所在国家。
`language_name`	string	条件填	搜索引擎语言名称。未指定 `language_code` 时填。支持：`English`、`French`、`German`。
`language_code`	string	条件填	搜索引擎语言代码。未指定 `language_name` 时填。支持：`en`、`fr`、`de`。
`device`	string	否	设备类型。可选值：`all`、`mobile`、`desktop`、`tablet`。默认值：`all`。
`sort_by`	string	否	结果排序字段，支持 `search_volume`、`cpc`、`competition`、`relevance`。结果按降序排列。默认值：`relevance`。
`date_from`	string	否	数据起始日期，格式为 `yyyy-mm-dd`，例如 `2020-01-01`。不传时默认返回最近 12 个月数据。最早可查询至当前日期前两年；可用范围取决于数据是否为数据。
`date_to`	string	否	数据结束日期，格式为 `yyyy-mm-dd`，例如 `2020-03-15`。不传时默认返回最近 12 个月数据。最早可查询至当前日期前两年，最晚可设置为当前日期前一个月。
`search_partners`	boolean	否	是否 Bing 搜索合作伙伴网络的数据。`true` 表示 Bing、Yahoo、AOL 及合作伙伴网站；默认值为 `false`，返回 Bing、AOL 和 Yahoo 搜索网络数据。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样出现在响应任务的 `data` 对象中，便于请求与结果。

日期参数说明

如果状态接口 /v3/keywords_data/bing/status/ 的 actual_data 为 false，date_from 可设置为上上个月及更早日期。
如果 actual_data 为 true，date_from 可设置为上个月及更早日期。
不建议针对过去一年使用自定义日期范围。

位置列表

可通过以下接口获取 Bing 支持的位置及对应编码：

GET /v3/keywords_data/bing/locations

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/bing/search_volume/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "language_name": "English",
      "device": "mobile",
      "keywords": [
        "tom and jerry",
        "silicon valley",
        "spider man"
      ]
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/bing/search_volume/live"

payload = [
    {
        "location_name": "United States",
        "language_name": "English",
        "device": "mobile",
        "keywords": [
            "tom and jerry",
            "silicon valley",
            "spider man"
        ]
    }
]

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

response = requests.post(url, json=payload, headers=headers)
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 response = await axios.post(
  "https://api.seermartech.cn/v3/keywords_data/bing/search_volume/live",
  [
    {
      location_name: "United States",
      language_name: "English",
      device: "mobile",
      keywords: [
        "tom and jerry",
        "silicon valley",
        "spider man"
      ]
    }
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json"
    }
  }
);

if (response.data.status_code === 20000) {
  console.log(response.data);
} else {
  console.error(
    `请求失败，状态码：${response.data.status_code}，消息：${response.data.status_message}`
  );
}

响应结构

接口返回 JSON 对象，主要 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。成功通常为 `20000`。
`status_message`	string	请求级提示信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果数量。
`path`	array	请求路径信息。
`data`	object	本次请求中提交的参数。
`result`	array	搜索量结果数组。

`result` 字段

字段	类型	说明
`keyword`	string	请求中的。
`location_code`	integer	位置编码。无数据时为 `null`。
`language_code`	string	语言代码。无数据时为 `null`。
`search_partners`	boolean	是否搜索合作伙伴网络数据。
`device`	string	设备类型。无数据时为 `null`。
`competition`	float	付费搜索竞争度，基于 Bing Ads 数据。可能值为 `0.1`、`0.5`、`0.9`，分别表示低、中、高竞争度。无数据时为 `null`。
`cpc`	float	该历史平均每次点击费用，单位为人民币。无数据时为 `null`。
`search_volume`	integer	月均搜索量，通常为近似值，并四舍五到最接近的十位数。无数据时为 `null`。
`categories`	array	产品或服务分类。本接口不返回分类，该字段始终为 `null`。
`monthly_searches`	array	按指定地理位置统计的月度搜索量，通常提供最近 12 个月的数据。无数据时为 `null`。

`monthly_searches` 字段

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	当月搜索量，通常为近似值，并四舍五到最接近的十位数。

响应示例

json

{
  "version": "0.1.20200923",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "8.2899 sec.",
  "cost": 0.54,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "8.1000 sec.",
      "cost": 0.54,
      "result_count": 2,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "search_volume",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "search_volume",
        "se": "bing",
        "location_name": "United States",
        "language_code": "en",
        "device": "mobile",
        "keywords": [
          "tom and jerry",
          "silicon valley",
          "spider man"
        ]
      },
      "result": [
        {
          "keyword": "tom and jerry",
          "location_code": 2840,
          "language_code": "en",
          "search_partners": false,
          "device": "mobile",
          "competition": 0.9,
          "cpc": 0.36,
          "search_volume": 3220,
          "categories": null,
          "monthly_searches": [
            {
              "year": 2024,
              "month": 1,
              "search_volume": 3200
            }
          ]
        },
        {
          "keyword": "silicon valley",
          "location_code": 2840,
          "language_code": "en",
          "search_partners": false,
          "device": "mobile",
          "competition": 0.1,
          "cpc": 0,
          "search_volume": 0,
          "categories": null,
          "monthly_searches": []
        }
      ]
    }
  ]
}

状态码与错误处理

请根据顶层或任务级别的 status_code 和 status_message 判断请求是否成功：

20000：请求成功。
状态码：请求或任务处理失败，应结合 status_message 排查参数、认证、频率限制或服务状态。
即使 HTTP 请求成功，也应继续检查 JSON 中的 status_code。
建议在业务系统中实现异常重试、错误记录和任务结果校验机制。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

实用场景

筛选高搜索量：批量获取目标市场的月均搜索量，优确定规划和落地页建设方向。
评估付费搜索竞争度：结合 competition 与 cpc 判断投放难度和预算压力，优化广告组合。
分析季节趋势：利用 monthly_searches 对比近 12 至 24 个月的搜索变化，安排季节性和促销活动。
对比不同设备需求：分别查询移动端、桌面端和平板端搜索量，为移动 SEO 和设备定向投放提供依据。
验证地域与语言市场机会：按位置、语言和搜索合作伙伴网络拆分数据，支持海外市场和本地化 SEO 决策。

keywords_data/bing/search_volume/live ​

接口说明 ​

请求参数 ​

日期参数说明 ​

位置列表 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 字段 ​

result 字段 ​

monthly_searches 字段 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​