Bing 搜索量历史任务创建

POST /v3/keywords_data/bing/search_volume_history/task_post

接口说明

POST /v3/keywords_data/bing/search_volume_history/task_post

本接口用于创建 Bing 历史搜索量查询任务。单个请求最多可查询 1000 个，并支持按月、周或日返回搜索量数据，同时可指定设备类型。

这是异步的标准任务模式：

提交任务后获取任务 ID。
系统完成数据采集后，通过任务结果接口查询数据，或通过 postback_url / pingback_url 接收通知。
任务执行时间取决于系统负载。

如需实时返回结果，可使用 Live 模式接口：

/v3/keywords_data/bing/search_volume/live

历史数据最长可追溯至过去两年。

计费说明

本接口在创建任务时计费，与单个任务中的数量无。无论 keywords 数组 1 个还是 1000 个，单个任务的计费方式相同。

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

请求要求

请求方法：POST
请求路径：/v3/keywords_data/bing/search_volume_history/task_post
请求格式：JSON，使用 UTF-8 编码
请求体是 JSON 数组：[{ ... }]
单次请求最多 100 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准
如果单次请求 100 个任务，出部分将返回错误码 40006
单个任务的 keywords 数组最多 1000 个
每个最长 100 个字符
会被转换为小写，并在结果中以独立数组返回

可通过以下接口获取 Bing 支持的地点和语言列表：

GET /v3/keywords_data/bing/search_volume_history/locations_and_languages

请求参数

参数名	类型	填	说明
`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	条件填	地点 GPS 坐标，格式为 `"纬度,经度"`。未指定 `location_name` 或 `location_code` 时填。返回数据所属国家以坐标所在国家为准。示例：`52.6178549,-155.352142`
`language_name`	string	否	语言名称。
`language_code`	string	否	语言代码，例如 `en`。
`device`	array	否	设备类型。可选值：`mobile`、`desktop`、`tablet`、`non_smartphones`。
`period`	string	否	数据聚合周期。可选值：`monthly`、`weekly`、`daily`。默认值为 `monthly`。
`date_from`	string	否	数据起始日期，格式为 `yyyy-mm-dd`。最早可设置为两年前的日期。
`date_to`	string	否	数据结束日期，格式为 `yyyy-mm-dd`。最晚可设置为今天之后一天。
`postback_url`	string	否	任务完成后，本平台将向该地址发送结果的 POST 请求，使用 gzip 压缩。
`pingback_url`	string	否	任务完成后，本平台将向该地址发送 GET 请求进行通知。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会在响应的 `data` 对象中返回。

`period` 的取值范围

值	返回范围
`monthly`	最多过去 24 个月
`weekly`	最多过去 15 周
`daily`	最多过去 45 天

默认，如果未指定 date_from 和 date_to，将返回过去 24 个月的数据。

日期参数说明

date_from 的最早值为当前日期往前两年。
当状态接口返回的 actual_data 为 false 时，date_from 可设置为上上个月及更早日期。
当状态接口返回的 actual_data 为 true 时，date_from 可设置为上个月及更早日期。
date_to 最晚可设置为当前日期之后一天。
日期格式为 "yyyy-mm-dd"。
不建议使用自定义时间范围。
如果指定 period=weekly，默认返回过去 15 周。
如果指定 period=daily，默认返回过去 45 天。

状态接口：

GET /v3/keywords_data/bing/status

回调地址变量

在 postback_url 或 pingback_url 中可以使用以下变量：

$id：任务 ID
$tag：经过 URL 编码的任务标签

示例：

text

https://your-server.com/postbackscript?id=$id&tag=$tag
https://your-server.com/pingscript?id=$id&tag=$tag

回调地址中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23>。

如果接收回调的服务器在 10 秒未返回响应，连接将因时中断，任务会转移到任务就绪列表。服务器返回的错误码和错误信息取决于接收端。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/bing/search_volume_history/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "language_code": "en",
      "keywords": [
        "average page rpm adsense",
        "adsense blank ads how long"
      ],
      "device": [
        "desktop",
        "mobile"
      ],
      "period": "monthly",
      "tag": "bing_volume_2024_001"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/bing/search_volume_history/task_post"

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

payload = [
    {
        "location_name": "United States",
        "language_code": "en",
        "keywords": [
            "average page rpm adsense",
            "adsense blank ads how long",
        ],
        "period": "monthly",
        "tag": "some_string_123",
        "pingback_url": (
            "https://your-server.com/pingscript?id=$id&tag=$tag"
        ),
    },
    {
        "location_code": 2840,
        "language_name": "English",
        "keywords": [
            "leads and prospects",
        ],
        "postback_url": "https://your-server.com/postbackscript",
    },
]

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()

result = response.json()
if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败：{result.get('status_code')} "
        f"{result.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    location_name: "United States",
    language_code: "en",
    keywords: [
      "average page rpm adsense",
      "adsense blank ads how long",
    ],
    period: "monthly",
    tag: "some_string_123",
    pingback_url:
      "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/bing/search_volume_history/task_post",
    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 数据 tasks 数组。每个提交的任务对应一个 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 格式。后续可使用该 ID 查询任务结果。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。创建任务时通常为 `0`。
`path`	array	请求路径信息。
`data`	object	创建任务时提交的参数。
`result`	array/null	任务结果。刚创建任务时为 `null`。

完整状态码请参考错误码文档：/v3/appendix/errors

响应示例

json

{
  "version": "0.1.20240626",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0611 sec.",
  "cost": 0.05,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0100 sec.",
      "cost": 0.05,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "search_volume_history",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "search_volume_history",
        "se": "bing",
        "location_code": 2840,
        "language_code": "en",
        "keywords": [
          "average page rpm adsense"
        ]
      },
      "result": null
    }
  ]
}

结果获取方式

任务创建成功后，可通过返回的 id 查询任务结果。也可以在创建任务时：

postback_url：任务完成后接收结果的 POST 请求。
pingback_url：任务完成后接收 GET 通知，再使用任务 ID获取结果。

实用场景

监测季节性趋势：按月或按周对比历史搜索量，识别旺季、淡季及发布窗口，优化 SEO排期。
评估增长潜力：批量获取候选的长期搜索量变化，筛选持续增长且值得的目标词。
制定地区化策略：结合地点名称或地点代码分析不同市场的搜索需求，为本地化落地页和区域 SEO 规划提供依据。
拆分设备端搜索需求：分别查询移动端、桌面端和平板端搜索量，优化移动优页面、广告投放和设备端转化策略。
构建监控任务：通过 tag、postback_url 或 pingback_url 自动任务与业务系统，持续更新趋势看板。

Bing 搜索量历史任务创建 ​

接口说明 ​

计费说明 ​

请求要求 ​

请求参数 ​

period 的取值范围 ​

日期参数说明 ​

回调地址变量 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks素字段 ​

响应示例 ​

结果获取方式 ​

实用场景 ​