keywords_data/bing/keywords_for_category/live

GET /v3/keywords_data/bing/locations

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

/v3/keywords_data/bing/keywords_for_category/live

接口说明

本接口根据指定的 Bing 产品或服务分类，实时返回及数据：

最近一个月的搜索量；
最多过去 24 个月的搜索量趋势；
付费搜索中的竞争度；
平均每次点击费用（CPC）；
所属的产品或服务分类。

指定分类返回的列表与地域无，但竞争度、CPC、搜索量和月度搜索量会根据请求中设置的地域返回。

如果业务需要实时获取结果，建议使用本接口。与异步任务接口相比，本接口无需分别调用任务提交和结果获取接口。

历史数据最长可查询 24 个月。

计费说明

每次请求均会产生费用。当前接口参考价约 ¥0.54 / 次。

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

单个请求最多返回 3000 条建议。平台限流以认证说明中的 30/60/120 次/分钟规则为准。

所有 POST 请求体使用 UTF-8 编码的 JSON 格式，并且是 JSON 数组：

json

[
  {
    "category_code": 13895,
    "location_name": "United States",
    "language_name": "English"
  }
]

请求参数

参数	类型	填	说明
`category_code`	integer	是	Bing 产品或服务分类 ID。可通过 `GET /v3/keywords_data/bing/categories` 获取可用分类列表。
`location_name`	string	条件填	搜索引擎地域的完整名称。当未指定 `location_code` 或 `location_coordinate` 时填。使用此参数后，无需再传地域参数。可通过 `GET /v3/keywords_data/bing/locations` 获取可用地域及名称。示例：`London,England,United Kingdom`
`location_code`	integer	条件填	搜索引擎地域代码。当未指定 `location_name` 或 `location_coordinate` 时填。示例：`2840`
`location_coordinate`	string	条件填	地域 GPS 坐标，格式为 `纬度,经度`。当未指定 `location_name` 或 `location_code` 时填。数据将坐标所属国家返回。示例：`52.6178549,-155.352142`
`language_name`	string	条件填	搜索引擎语言完整名称。当未指定 `language_code` 时填。目前支持：`English`。
`language_code`	string	条件填	搜索引擎语言代码。当未指定 `language_name` 时填。目前支持：`en`。
`keywords_negative`	array	否	需要从结果中排除的列表，最多支持 200 个词组。传的会被转换为小写。
`device`	string	否	设备类型。可选值：`desktop`、`mobile`、`tablet`、`all`。默认值：`all`。
`date_from`	string	否	时间范围起始日期，格式为 `yyyy-mm-dd`。最早可查询至当前日期前 24 个月。未指定时，返回最近 12 个月的数据。示例：`2020-01-01`
`date_to`	string	否	时间范围结束日期，格式为 `yyyy-mm-dd`。最早可查询至当前日期前两年，最晚可设置为当前日期后一个月。未指定时，返回最近 12 个月的数据。示例：`2020-03-15`。不建议对过去一年的日期使用自定义时间范围。
`sort_by`	string	否	结果排序字段，支持 `search_volume`、`competition`、`cpc` 和 `relevance`，按降序排列。默认值：`relevance`。
`search_partners`	boolean	否	是否 Bing 搜索合作伙伴网络的数据。`true` 表示 Bing、Yahoo、AOL 及托管这些搜索服务的合作伙伴网站；默认值为 `false`，返回 Bing、AOL 和 Yahoo 搜索网络的数据。
`tag`	string	否	自定义任务标识，最长 255 个字符。可用于请求与响应，传的值会在响应的 `data` 对象中返回。

地域参数互斥规则

以下三个参数只能选择一个：

location_name
location_code
location_coordinate

语言参数互斥规则

以下两个参数只能选择一个：

language_name
language_code

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/bing/keywords_for_category/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "language_name": "English",
      "category_code": 13895,
      "device": "all",
      "sort_by": "relevance"
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "location_name": "United States",
        "language_name": "English",
        "category_code": 13895,
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=120)
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 payload = [
  {
    location_name: "United States",
    language_name: "English",
    category_code: 13895,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/bing/keywords_for_category/live",
    payload,
    {
      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);
  });

响应结构

接口返回 JSON 数据，主要结构如下：

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。完整错误码请参考错误码文档。
`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	请求 URL 路径信息。
`data`	object	请求中提交的任务参数。
`result`	array	结果数组。

`result` 数组字段

字段	类型	说明
`keyword`	string	。
`location_code`	integer	搜索引擎地域代码。无数据时为 `null`。
`language_code`	string	搜索引擎语言代码。无数据时为 `null`。
`search_partners`	boolean	是否搜索合作伙伴网络数据。
`device`	string	数据对应的设备类型。无数据时为 `null`。
`competition`	float	付费搜索竞争度，取值范围为 `0` 至 `1`，边界值。该值基于 Bing Ads 数据表示付费搜索结果中的相对竞争程度。无数据时为 `null`。
`cpc`	float	平均每次点击费用。表示历史上该的平均付费点击成本，原始数据单位为。无数据时为 `null`。
`search_volume`	integer	最近一个月的平均搜索量，表示该在 Bing 上触发的搜索次数。无数据时为 `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": "10.1792 sec.",
  "cost": 0.075,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "10.1792 sec.",
      "cost": 0.075,
      "result_count": 3,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "keywords_for_category",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "keywords_for_category",
        "se": "bing",
        "location_code": 2840,
        "language_code": "en",
        "category_code": 10003
      },
      "result": [
        {
          "keyword": "oculus rift",
          "location_code": 2840,
          "language_code": "en",
          "search_partners": false,
          "device": "all",
          "competition": 0.9,
          "cpc": 0.21,
          "search_volume": 34150,
          "categories": [
            10003
          ],
          "monthly_searches": [
            {
              "year": 2020,
              "month": 1,
              "search_volume": 34150
            }
          ]
        },
        {
          "keyword": "discover personal loans",
          "location_code": 2840,
          "language_code": "en",
          "search_partners": false,
          "device": "all",
          "competition": 0.9,
          "cpc": 1.46,
          "search_volume": 21890,
          "categories": [
            10003
          ],
          "monthly_searches": [
            {
              "year": 2020,
              "month": 1,
              "search_volume": 21890
            }
          ]
        },
        {
          "keyword": "home warranty companies",
          "location_code": 2840,
          "language_code": "en",
          "search_partners": false,
          "device": "all",
          "competition": 0.9,
          "cpc": 1.98,
          "search_volume": 17220,
          "categories": [
            10003
          ],
          "monthly_searches": [
            {
              "year": 2020,
              "month": 1,
              "search_volume": 17220
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

建议客户端同时检查以下状态信息：

HTTP 状态码；
顶层 status_code；
任务级 tasks[].status_code；
status_message 和 tasks[].status_message。

当 tasks_error 大于 0 时，应逐项检查对应任务的状态码和错误消息，并根据错误类型执行重试、修正参数或记录失败任务。

实用场景

挖掘指定产品分类下的，快速建立 Bing SEO选题库并扩大覆盖范围。
比较不同地域的搜索需求，识别目标市场的热度差异，为本地化 SEO 和市场策略提供依据。
分析过去 12 至 24 个月的搜索趋势，发现季节性需求和增长，优化发布时间与资源。
结合搜索量、竞争度和 CPC 筛选，优选择流量潜力和商业价值的 SEO 目标词。
按设备类型拆分数据，比较桌面端、移动端和平板端的搜索需求，为移动端和页面优化提供依据。

keywords_data/bing/keywords_for_category/live ​

接口说明 ​

计费说明 ​

请求参数 ​

地域参数互斥规则 ​

语言参数互斥规则 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

tasks 对象字段 ​

result 数组字段 ​

monthly_searches 数组字段 ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​