获取 Bing 搜索量历史任务结果

本接口使用 GET 方法，通过任务 ID 获取 Bing「搜索量历史」任务结果：

GET https://api.seermartech.cn/v3/keywords_data/bing/search_volume_history/task_get/$id

单次任务最多支持 1000 个。搜索量历史数据可按月、周或日返回，并支持指定设备类型。任务提交成功后，可在 30 天获取任务结果。

计费说明

本接口在提交任务时计费，任务结果可在 30 天重复获取，不额外收费。

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

请求参数

接口通过 URL 路径传任务 ID，无需请求体。

参数	类型	说明
`id`	string	任务唯一标识，UUID 格式。任务提交后 30 天可使用该 ID 获取结果。

请求示例

cURL

bash

id="10081455-0001-0110-0000-c75b21dcca1c"

curl --location --request GET \
  "https://api.seermartech.cn/v3/keywords_data/bing/search_volume_history/task_get/${id}" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

TypeScript

typescript

import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios
  .get(
    `https://api.seermartech.cn/v3/keywords_data/bing/search_volume_history/task_get/${taskId}`,
    {
      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);
  });

Python

python

import requests

task_id = "02231934-2604-0066-2000-570459f04879"
url = (
    "https://api.seermartech.cn/v3/keywords_data/bing/"
    f"search_volume_history/task_get/{task_id}"
)

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
)

if response.ok:
    # 处理任务结果
    print(response.json())
else:
    print(f"请求失败：{response.status_code} {response.text}")

响应结构

服务器返回 JSON 对象 tasks 数组任务结果。

顶层字段

字段	类型	说明
`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	搜索量历史结果数组。

`data` 字段

data 通常以下任务参数：

字段	类型	说明
`api`	string	API 类型，通常为 `keywords_data`。
`function`	string	功能名称，通常为 `search_volume_history`。
`se`	string	搜索引擎，固定为 `bing`。
`id`	string	任务 ID。
`location_code`	integer	地理位置编码。无对应数据时，结果字段可能为 `null`。
`language_code`	string	语言编码。无对应数据时，结果字段可能为 `null`。
`keywords`	array	请求中提交的列表。

`result` 结果字段

字段	类型	说明
`keyword`	string	请求中的。
`location_code`	integer	请求中的地理位置编码。无数据时可能为 `null`。
`language_code`	string	请求中的语言编码。无数据时可能为 `null`。
`device`	string	请求中的设备类型。无数据时可能为 `null`。
`period`	string	搜索量数据周期，例如 `monthly`、`weekly` 或 `daily`。
`searches`	object	按设备类型划分的历史搜索量数据。

`searches` 设备字段

searches 对象可以下设备类型：

字段	类型	说明
`desktop`	object / array	桌面设备的历史搜索量数据。
`non_smartphones`	object / array	功能手机等非智能手机设备的历史搜索量数据。
`mobile`	object / array	移动设备的历史搜索量数据。
`tablet`	object / array	平板设备的历史搜索量数据。

每条设备搜索量记录以下字段：

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`day`	integer	日期中的日。按月或按周统计时，日期可能根据返回周期确定。
`search_volume`	integer	对应时间段的搜索量。

响应示例

json

{
  "version": "0.1.20240626",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.12 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "07101317-1535-0260-0000-5f5e20c3d82e",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.10 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "/v3/keywords_data/bing/search_volume_history/task_get/07101317-1535-0260-0000-5f5e20c3d82e"
      ],
      "data": {
        "api": "keywords_data",
        "function": "search_volume_history",
        "se": "bing",
        "id": "07101317-1535-0260-0000-5f5e20c3d82e",
        "location_code": 2840,
        "language_code": "en",
        "keywords": [
          "seo tools"
        ]
      },
      "result": [
        {
          "keyword": "seo tools",
          "location_code": 2840,
          "language_code": "en",
          "device": "desktop",
          "period": "monthly",
          "searches": {
            "desktop": [
              {
                "year": 2024,
                "month": 6,
                "day": 1,
                "search_volume": 5400
              }
            ],
            "non_smartphones": [],
            "mobile": [
              {
                "year": 2024,
                "month": 6,
                "day": 1,
                "search_volume": 2900
              }
            ],
            "tablet": [
              {
                "year": 2024,
                "month": 6,
                "day": 1,
                "search_volume": 300
              }
            ]
          }
        }
      ]
    }
  ]
}

状态码与错误处理

请根据以下字段判断请求和任务是否成功：

顶层 status_code：判断整个 API 请求是否成功。
tasks[].status_code：判断任务是否成功。
status_message：获取对应的状态说明。
tasks_error：确认是否存在返回错误的任务。

建议在客户端实现以下处理逻辑：

检查 HTTP 状态码和顶层 status_code。
遍历 tasks，单独检查每个任务的 status_code。
在任务成功且 result 不为空时处理搜索量数据。
对 result、searches 及设备类型字段进行空值判断。
对时、任务不存在、任务尚未完成和结果为空等进行重试或记录。

实用场景

对比不同月份的 Bing 搜索量：识别需求变化，优化发布节奏和季度 SEO 规划。
拆分桌面端与移动端搜索趋势：评估用户设备结构，为移动端页面优化和独立策略提供依据。
监测核心的季节性波动：发现周期性需求高峰，提前安排专题页、促销页和广告预算。
批量分析历史表现：一次获取最多 1000 个的数据，为筛选、聚类和优级排序提供数据支持。
比较不同地区或语言的搜索需求：结合位置编码和语言编码分析市场差异，化 SEO 和区域布局。

获取 Bing 搜索量历史任务结果 ​

计费说明 ​

请求参数 ​

请求示例 ​

cURL ​

TypeScript ​

Python ​

响应结构 ​

顶层字段 ​

tasks 任务字段 ​

data 字段 ​

result 结果字段 ​

searches 设备字段 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​