Bing 效果任务创建

接口说明

通过本接口可以为一组创建 Bing 效果 查询任务，并在任务完成后获取对应的效果指标。返回数据会基于你指定的：

匹类型
地域
语言
设备类型

结果中可最近一个月聚合后的效果数据，例如：

广告位置
点击量
展现量
表现指标

你在 POST 数组中提交的每个任务，都会分别生成独立结果。

这是标准异步模式的数据获取方式：创建任务，再在任务执行完成后获取结果。若你不要求实时返回，这种方式通常更稳定、也更适合批量处理。任务执行时间取决于系统负载。

如果你的业务需要即时结果，可改用 /v3/keywords_data/bing/keyword_performance/live。

数据更新时间说明

Bing 通常会在每月第 3 天之后更新上一个自然月的数据。

例如：

若你在 8 月 1 日、2 日或 3 日请求数据，而 7 月数据尚未可用，则接口会返回 6 月数据；
当 8 月 4 日后 Bing 完成更新，响应 result 数组中的 month 字段会表明数据已对应到上一个自然月。

请求方式

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

计费说明

在创建任务时扣费。

参考价约 ¥0.8000 / 次 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制

每分钟最多可发起 2000 次 API 调用
每次 POST 最多可 100 个任务
若单次 POST 中任务数 100，出部分将返回错误 40006
单个 keywords 数组最多可传 1000 个
无论 keywords 中是 1 个还是 1000 个，都按一次请求计费

回调与结果获取

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

使用任务唯一标识 id 查询已完成任务结果；
在创建任务时传 postback_url，任务完成后本平台会将结果以 gzip 压缩的 POST 请求推送到指定地址；
在创建任务时传 pingback_url，任务完成后本平台会通过 GET 请求通知你。

注意事项：

若你的服务器在 10 秒未响应，连接会因时中断； -时后，任务会转 tasks_ready 列表，供后续主动拉取；
返回的错误码与错误信息取决于你的服务端；
postback_url 和 pingback_url 中的特殊字符会进行 URL 编码，例如 # 会编码为 %23；
你可以在回调 URL 中使用 $id 和 $tag 变量，本平台会在发送前替换为值。

请求参数

POST 请求体为 JSON 数组格式：

json

[
 {
 "location_name": "United States",
 "language_name": "English",
 "keywords": ["seo", "ranking"]
 }
]

字段说明

字段名	类型	说明
`keywords`	array	填。数组。最多 1000 个；每个最长 80 个字符；每个短语最多 10 个单词。系统会将自动转换为小写，结果将按分别返回。
`device`	string	可选。设备类型。可选值：`desktop`、`mobile`、`tablet`、`all`。默认值：`all`。
`match`	string	可选。匹方式。可选值：`aggregate`、`broad`、`phrase`、`exact`。默认值：`aggregate`。：`aggregate` 表示聚合匹方式；`broad` 表示、词序可变化的查询；`phrase` 表示且词序一致的查询；`exact` 表示与匹的查询。
`location_name`	string	当未提供 `location_code` 或 `location_coordinate` 时填。搜索引擎地域名。使用该字段时，无需再传 `location_code` 或 `location_coordinate`。示例：`United States`。可通过 `/v3/keywords_data/bing/keyword_performance/locations_and_languages` 获取可用地域和语言。
`location_code`	integer	当未提供 `location_name` 或 `location_coordinate` 时填。搜索引擎地域编码。使用该字段时，无需再传 `location_name` 或 `location_coordinate`。示例：`2840`。可通过 `/v3/keywords_data/bing/keyword_performance/locations_and_languages` 获取可用地域和语言。
`location_coordinate`	string	当未提供 `location_name` 或 `location_code` 时填。地理坐标，格式为 `"latitude,longitude"`。使用该字段时，无需再传 `location_name` 或 `location_code`。返回数据将对应到该坐标所属国家。示例：`52.6178549,-155.352142`。
`language_name`	string	当未提供 `language_code` 时填。搜索引擎语言名称。使用该字段时，无需再传 `language_code`。示例：`English`。可通过 `/v3/keywords_data/bing/keyword_performance/locations_and_languages` 获取可用地域和语言。
`language_code`	string	当未提供 `language_name` 时填。搜索引擎语言编码。示例：`en`。可通过 `/v3/keywords_data/bing/keyword_performance/locations_and_languages` 获取可用地域和语言。
`postback_url`	string	可选。任务完成后，用于接收结果数据的回调地址。本平台会向该地址发送 POST 请求，结果为 gzip 压缩格式。支持 `$id` 与 `$tag` 占位符。示例：`http://your-server.com/postbackscript?id=$id`、`http://your-server.com/postbackscript?id=$id&tag=$tag`。
`pingback_url`	string	可选。任务完成通知地址。本平台会向该地址发送 GET 请求。支持 `$id` 与 `$tag` 占位符。示例：`http://your-server.com/pingscript?id=$id`、`http://your-server.com/pingscript?id=$id&tag=$tag`。
`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` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 数组字段说明

字段名	类型	说明
`id`	string	本平台任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，范围通常为 `10000-60000`。完整错误码可参考 `/v3/appendix/errors`。
`status_message`	string	任务状态信息。
`time`	string	任务处理耗时，单位秒。
`cost`	float	单个任务费用，单位为平台 USD。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求路径。
`data`	object	回显你在 POST 请求中提交的参数。
`result`	array\|null	任务创建阶段通常为 `null`。数据需在任务完成后获取。

请求示例

curl

bash

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "language_name": "English",
 "keywords": [
 "seo",
 "ranking",
 "keyword research"
 ],
 "device": "all",
 "match": "aggregate",
 "tag": "bing-kp-demo-001"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "location_name": "United States",
 "language_name": "English",
 "keywords": [
 "seo",
 "ranking",
 "keyword research"
 ],
 "device": "all",
 "match": "aggregate",
 "tag": "bing-kp-demo-001"
 }
]

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

TypeScript

typescript

import axios from "axios";

const postData = [
 {
 location_name: "United States",
 language_name: "English",
 keywords: ["seo", "ranking", "keyword research"],
 device: "all",
 match: "aggregate",
 tag: "bing-kp-demo-001"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/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.20201021",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0355 sec.",
 "cost": 0.05,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "c5c9b0b2-6b7e-4fa9-9c4b-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0012 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "bing",
 "keyword_performance",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keyword_performance",
 "se": "bing",
 "location_code": 2840,
 "language_code": "en",
 "keywords": [
 "seo",
 "ranking",
 "keyword research"
 ]
 },
 "result": null
 }
 ]
}

状态码与错误处理

顶层 status_code = 20000 表示请求成功；
任务级别状态请查看 tasks[].status_code；
若单次 POST 中任务数量 100，出部分会返回 40006；
建议同时处理：
请求级错误
任务级错误
回调时
参数缺失或格式错误

完整错误码可参考 /v3/appendix/errors。

使用建议

批量提交时，将多个任务放一个 JSON 数组中可提升吞吐效率；
若你只需某一设备类型的数据，建议显式传 device，减少无效结果；
若你对匹逻辑敏感，建议明确设置 match，使用默认值导致结果范围偏大；
若要做自动化任务跟踪，建议始终设置 tag；
若业务流程依赖异步处理完成通知，优 postback_url 或 pingback_url。

实用场景

监控品牌词广告表现：批量查询品牌词在 Bing 上的点击、展现和广告位置变化，帮助评估品牌投放覆盖度与搜索需求波动。
对比不同匹方式效果：分别使用 broad、phrase、exact 提交同一批，分析不同匹类型带来的流量差异，优化广告结构。
评估多地区潜力：按不同国家或坐标创建任务，比较同一在不同市场的表现，为化投放和本地化提供依据。
拆分设备端流量特征：分别获取 desktop、mobile、tablet 数据，识别移动端或桌面端更强势的词，指导落地页与出价策略优化。
建立月度景气度看板：定期提交核心词任务，持续记录最近月份的效果指标，用于趋势复盘、预算分和类目机会识别。

Bing 效果任务创建 ​

接口说明 ​

数据更新时间说明 ​

请求方式 ​

计费说明 ​

请求限制 ​

回调与结果获取 ​

请求参数 ​

字段说明 ​

响应结构 ​

顶层字段说明 ​

tasks 数组字段说明 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​