Bing 搜索量历史任务创建

POST /v3/keywords_data/bing/search_volume_history/task_post

接口说明

该接口用于创建 Bing 历史搜索量查询任务。单次请求最多可提交 1000 个，返回维度支持：

按月
按周
按日

同时可指定设备类型。

这是标准任务模式：创建任务，系统完成数据采集后，再通过任务结果接口获取结果。如果你不要求实时返回，这种方式更适合批量、异步处理。任务执行时长取决于系统负载。

如果你的业务要求即时返回结果，建议改用实时（Live）方式：/v3/keywords_data/bing/search_volume/live/。

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

接口地址

POST https://api.seermartech.cn/v3/keywords_data/bing/search_volume_history/task_post

计费说明

该接口在创建任务时扣费。

原文未提供固定单价，因此无法直接换算为人民币参考价。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求规则

请求方法：POST
请求体格式：JSON
编码：UTF-8
请求体为 JSON 数组：[{ ... }]

频率与批量限制

每分钟最多 2000 次 API 调用
每次 POST 最多 100 个任务
若单次 POST 中任务数 100，出部分会返回错误：40006
每个任务中的 keywords 数组最多 1000 个
每个最大长度为 100 个字符

结果返回方式

你可以通过以下方式获取结果：

使用任务唯一标识 id 查询已完成任务；
创建任务时设置 postback_url，任务完成后由本平台主动 POST 结果；
创建任务时设置 pingback_url，任务完成后由本平台主动 GET 通知。

注意：
如果你的回调服务器在 10 秒未响应，连接会因时中断；
此类任务会被转 tasks_ready 列表；
实错误码与错误信息取决于你的服务器。

请求参数

以下字段用于创建任务。

字段名	类型	填	说明
`keywords`	array	是	列表。单个任务最多 1000 个；每个最大 100 个字符。系统会将统一转换为小写，并按分别返回数据。
`location_name`	string	条件填	搜索引擎地区完整名称。当未提供 `location_code` 或 `location_coordinate` 时填。使用该字段时无需再传 `location_code`、`location_coordinate`。示例：`London,England,United Kingdom`
`location_code`	integer	条件填	搜索引擎地区代码。当未提供 `location_name` 或 `location_coordinate` 时填。使用该字段时无需再传 `location_name`、`location_coordinate`。示例：`2840`
`location_coordinate`	string	条件填	地理坐标，格式为 `"latitude,longitude"`。当未提供 `location_name` 或 `location_code` 时填。使用该字段时无需再传 `location_name`、`location_code`。返回数据按该坐标所属国家提供。示例：`52.6178549,-155.352142`
`language_name`	string	条件填	搜索引擎语言完整名称。当未提供 `language_code` 时填。使用该字段时无需再传 `language_code`。
`language_code`	string	条件填	搜索引擎语言代码。当未提供 `language_name` 时填。使用该字段时无需再传 `language_name`。
`device`	array	否	设备类型过滤。可选值：`mobile`、`desktop`、`tablet`、`non_smartphones`。默认不限制设备。
`period`	string	否	返回数据聚合周期。可选值：`monthly`、`weekly`、`daily`。默认：`monthly`。
`date_from`	string	否	时间范围起始日期，格式：`yyyy-mm-dd`。最早可到当前日期往前两年，最晚为当前日期前一天。示例：`2020-01-01`
`date_to`	string	否	时间范围结束日期，格式：`yyyy-mm-dd`。最早可到当前日期往前两年，最晚为当前日期前一天。示例：`2020-03-15`
`postback_url`	string	否	任务完成后，平台会向该地址发送 POST 请求，并以 `gzip` 压缩格式传输结果。支持在 URL 中使用 `$id` 和 `$tag` 占位符。
`pingback_url`	string	否	任务完成后，平台会向该地址发送 GET 通知。支持在 URL 中使用 `$id` 和 `$tag` 占位符。
`tag`	string	否	自定义任务标识，最大 255 字符。可用于结果匹与业务追踪。该值会出现在响应的 `data` 对象中。

参数补说明

地区与语言列表获取

可通过以下容路径获取支持的地区与语言：

/v3/keywords_data/bing/search_volume_history/locations_and_languages

`period` 返回范围

当未指定 date_from 和 date_to 时，不同周期的默认返回范围如下：

monthly：过去 24 个月
weekly：过去 15 周
daily：过去 45 天

自定义时间范围说明

date_from、date_to 都是可选参数；
平台 API 不推荐使用自定义时间范围；
若未传这两个字段，将按 period 的默认范围返回数据。

回调地址占位符

postback_url 和 pingback_url 支持以下占位符：

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

示例：

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

注意：回调 URL 中的特殊字符会被 URL 编码，例如 # 会被编码为 %23。

响应结构

接口返回 JSON 编码数据， tasks 数组。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	局状态码，完整列表参考 `/v3/appendix/errors`
`status_message`	string	局状态信息
`time`	string	执行时间，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	返回错误的任务数量
`tasks`	array	任务结果数组

`tasks` 数组字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态说明
`time`	string	任务执行时间，单位秒
`cost`	float	任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	请求路径
`data`	object	回显你在 POST 请求中提交的参数
`result`	array	结果数组；在任务创建接口中，该值通常为 `null`

请求示例

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_name": "English",
 "keywords": [
 "average page rpm adsense",
 "leads and prospects"
 ],
 "period": "monthly"
 }
 ]'

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 = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keywords": [
 "adsense blank ads how long"
 ],
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "keywords": [
 "leads and prospects"
 ],
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript

typescript

import axios from "axios";

const postData = [
 {
 language_code: "en",
 location_code: 2840,
 keywords: ["adsense blank ads how long"],
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
];

axios({
 method: "post",
 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"
 },
 data: postData
})
 .then((response) => {
 // 输出任务创建结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

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": "12345678-1234-1234-1234-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0020 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
 }
 ]
}

状态码与错误处理

建议你在接时建立完善的异常处理机制，重点以下几类：

顶层 status_code 不为 20000
tasks_error 大于 0
单个任务的 status_code 非成功状态
单次 POST过 100 个任务时出现 40006
回调地址时或不可达，导致任务 tasks_ready

完整错误码请参考容路径：

/v3/appendix/errors

使用建议

批量历史搜索量查询，优使用任务模式，降低实时接口压力；
若只需标准最近时间窗口，尽量不要自定义 date_from / date_to；
当你需要按设备拆分趋势时，可传 device；
如需自动化接收结果，优 postback_url 或 pingback_url；
若要做业务侧任务追踪，建议为每个任务设置 tag。

实用场景

监控热度变化：按月、周、日获取历史搜索量，识别品牌词、品类词或活动词的波动趋势。
对比设备搜索行为：按 mobile、desktop 等设备拆分历史搜索量，制定移动端与桌面端 SEO 策略。
评估季节性需求：拉取过去两年的搜索量序列，判断行业淡旺季，为排期和投放节奏提供依据。
批量验证选题潜力：一次提交大量候选，快速筛选长期稳定增长或阶段性爆发的主题。
构建趋势预警系统：结合 pingback_url 或 postback_url 异步获取结果，自动接看板、报表或异常监控流程。

Bing 搜索量历史任务创建 ​

接口说明 ​

接口地址 ​

计费说明 ​

请求规则 ​

频率与批量限制 ​

结果返回方式 ​

请求参数 ​

参数补说明 ​

地区与语言列表获取 ​

period 返回范围 ​

自定义时间范围说明 ​

回调地址占位符 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​