提交 Bing 类目挖掘任务

POST /v3/keywords_data/bing/keywords_for_category/task_post

接口说明

通过本接口可为指定的 Bing 商品或服务类目创建挖掘任务。任务完成后，系统会返回该类目下的建议，以及以下核心数据：

上月搜索量
最多近 24 个月的搜索趋势
当前平均点击价格（CPC）
付费搜索竞争度

需要注意：

返回的集合本身不因地区不同而变化
但 competition、cpc、search volume、monthly searches 等指标会基于你设置的地区返回本地化数据

这是标准异步模式接口。若不要求实时返回，推荐使用该方式：创建任务，再在任务完成后获取结果。执行时间取决于系统负载。

如果你需要即时结果，可改用实时接口 /v3/keywords_data/bing/keywords_for_category/live/，该方式无需分别调用 POST 和结果查询接口。

历史数据最长可提供 24 个月。

请求地址

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

计费说明

该接口按创建任务计费。

参考价约 ¥0.8000 / 次

说明：

单次请求最多可返回 700 个建议及指标
无论最终返回 1 个还是 700 个，单个任务计费相同
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求规则

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

频率与数量限制

每分钟最多提交 2000 次 API 调用
每次 POST 最多 100 个任务
若单次请求中任务数 100，出部分会返回错误 40006

回调与结果获取

任务提交成功后，你可以通过以下方式获取结果：

使用任务唯一标识 id 查询已完成任务结果
创建任务时设置 postback_url，任务完成后系统会将结果以 gzip 压缩的 POST 请求推送到指定地址
创建任务时设置 pingback_url，任务完成后系统会向指定地址发送 GET 通知

注意事项：

若你的服务器在 10 秒未响应，连接会因时被中断
此类任务会被转对应的 tasks_ready 列表，之后可再自行获取结果
回调失败时的错误码与错误信息取决于你的服务端

请求参数

以下为创建任务时可用字段。

字段名	类型	说明
`category_code`	integer	类目 ID，填。可通过 `/v3/keywords_data/bing/categories` 获取可用的 Bing 商品与服务类目列表。
`location_name`	string	搜索引擎地区名。若未提供 `location_code` 或 `location_coordinate`，则为填；使用该字段时，无需再传 `location_code` 或 `location_coordinate`。可通过 `/v3/keywords_data/bing/locations` 获取地区列表。示例：`London,England,United Kingdom`
`location_code`	integer	搜索引擎地区编码。若未提供 `location_name` 或 `location_coordinate`，则为填；使用该字段时，无需再传 `location_name` 或 `location_coordinate`。可通过 `/v3/keywords_data/bing/locations` 获取地区编码。示例：`2840`
`location_coordinate`	string	地理坐标。若未提供 `location_name` 或 `location_code`，则为填；使用该字段时，无需再传 `location_name` 或 `location_code`。格式为 `"latitude,longitude"`。数据将按该坐标所属国家返回。示例：`52.6178549,-155.352142`
`language_name`	string	搜索语言名。若未提供 `language_code`，则为填。使用该字段时，无需再传 `language_code`。当前支持：`English`
`language_code`	string	搜索语言代码。若未提供 `language_name`，则为填。使用该字段时，无需再传 `language_name`。当前支持：`en`
`keywords_negative`	array	可选。负向数组；这些词将从结果中排除。最多可设置 200 个词条；系统会自动转为小写。
`device`	string	可选。设备类型，可选值：`desktop`、`mobile`、`tablet`、`all`。默认值：`all`
`date_from`	string	可选。时间范围起始日期。最早可设为距今 24 个月。未设置时默认返回最近 12 个月数据。格式：`"yyyy-mm-dd"`。示例：`"2020-01-01"`
`date_to`	string	可选。时间范围结束日期。未设置时默认返回最近 12 个月数据。最小值为距今两年前，最大值为距今一个月前。不建议对过去一年的日期使用自定义时间范围。格式：`"yyyy-mm-dd"`。示例：`"2020-03-15"`
`sort_by`	string	可选。结果排序字段，支持按 `search_volume`、`competition`、`cpc` 或 `relevance` 降序排序。默认值：`relevance`
`search_partners`	boolean	可选。Bing 搜索合作网络开。设为 `true` 时，结果将覆盖 Bing、Yahoo、AOL 及合作站点网络；默认值为 `false`，表示返回 Bing、AOL、Yahoo 搜索网络数据。
`postback_url`	string	可选。任务完成后用于接收结果的回调地址。系统会向该地址发送 gzip 压缩的 POST 请求。支持使用 `$id` 作为任务 ID 变量，`$tag` 作为 URL 编码后的标签变量。示例：`http://your-server.com/postbackscript?id=$id`、`http://your-server.com/postbackscript?id=$id&tag=$tag`。注意： URL 中特殊字符会被编码，例如 `#` 会变为 `%23`。
`pingback_url`	string	可选。任务完成通知地址。系统会向该地址发送 GET 请求。支持使用 `$id` 作为任务 ID 变量，`$tag` 作为 URL 编码后的标签变量。示例：`http://your-server.com/pingscript?id=$id`、`http://your-server.com/pingscript?id=$id&tag=$tag`。注意： URL 中特殊字符会被编码，例如 `#` 会变为 `%23`。
`tag`	string	可选。自定义任务标识，最大长度 255 字符。可用于任务与业务数据；响应中的 `data` 对象会原样返回该值。

响应说明

接口返回 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	与创建任务时传参数一致的数据对象
`result`	array	结果数组；对于 `task_post` 提交接口，此处通常为 `null`

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/bing/keywords_for_category/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "category_code": 13895
 },
 {
 "language_code": "en",
 "location_code": 2840,
 "category_code": 13895,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "category_code": 13895,
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/bing/keywords_for_category/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

data = [
 {
 # 最简单的任务提交方式
 "location_name": "United States",
 "category_code": 13895
 },
 {
 # 任务完成后，系统会向你指定的地址发送 GET 通知
 # $id 和 $tag 会被替换为任务值
 "language_code": "en",
 "location_code": 2840,
 "category_code": 13895,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 # 任务完成后，系统会向你指定的地址发送 POST 结果回调
 "location_name": "United States",
 "language_name": "English",
 "category_code": 13895,
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 // 最简单的任务提交方式
 location_name: "United States",
 category_code: 13895
 },
 {
 // 任务完成后，系统会向你指定的地址发送 GET 通知
 // $id 和 $tag 会被替换为任务值
 language_code: "en",
 location_code: 2840,
 category_code: 13895,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 // 任务完成后，系统会向你指定的地址发送 POST 结果回调
 location_name: "United States",
 language_name: "English",
 category_code: 13895,
 postback_url: "https://your-server.com/postbackscript"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/bing/keywords_for_category/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

json

{
 "version": "0.1.20200130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0683 sec.",
 "cost": 0.15,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "01301831-1535-0107-0000-0050e08f7b6c",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0024 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "bing",
 "keywords_for_category",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_category",
 "se": "bing",
 "location_name": "United States",
 "category_code": 13895
 },
 "result": null
 },
 {
 "id": "01301831-1535-0107-0000-21cc045291e0",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0020 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "bing",
 "keywords_for_category",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_category",
 "se": "bing",
 "language_code": "en",
 "location_code": 2840,
 "category_code": 13895,
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "tag": "some_string_123"
 },
 "result": null
 },
 {
 "id": "01301831-1535-0107-0000-77a3219d7e0b",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0022 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "bing",
 "keywords_for_category",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_category",
 "se": "bing",
 "language_name": "English",
 "location_name": "United States",
 "category_code": 13895,
 "postback_url": "https://your-server.com/postbackscript"
 },
 "result": null
 }
 ]
}

状态码说明

通用状态

状态码	说明
`20000`	请求成功
`20100`	任务已创建
`40006`	单次 POST 中的任务数量 100 个

建议在接时对异常和错误状态建立完整处理机制，是以下场景：

请求参数缺失或格式错误
回调地址不可达或时
任务量单次或分钟级限制
结果异步返回导致的轮询与重试处理

使用建议

若你只需要创建任务并稍后统一拉取，优使用本接口
若业务要求实时出数，改用 /v3/keywords_data/bing/keywords_for_category/live/
若需要提高结果可用性，建议为异步任务 pingback_url 或 postback_url
若要过滤不词，可结合 keywords_negative 限制输出范围
若要保证地区指标一致性，建议固定使用 location_code

实用场景

挖掘类目词：针对某个 Bing 商品或服务类目批量获取建议，快速建立广告投放或 SEO 词库。
评估地区需求：为同一类目设置不同地区参数，对比搜索量、CPC 与竞争度，市场优级判断。
过滤无流量：结合 keywords_negative 排除品牌词、低意图词或不词，提升候选质量。
构建趋势看板：利用近 24 个月历史趋势数据，分析类目需求季节性变化，支持规划和预算分。
自动化异步采集：通过 postback_url 或 pingback_url 接数据管道，在任务完成后自动库，降低人工轮询成本。

提交 Bing 类目挖掘任务 ​

接口说明 ​

计费说明 ​

请求规则 ​

频率与数量限制 ​

回调与结果获取 ​

请求参数 ​

响应说明 ​

顶层字段 ​

tasks 数组字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码说明 ​

通用状态 ​

使用建议 ​

实用场景 ​