设置扩展任务

POST /v3/keywords_data/bing/keywords_for_keywords/task_post

本接口使用 POST /v3/keywords_data/bing/keywords_for_keywords/task_post 创建 Bing 扩展任务。接口会根据指定，返回由 Bing Ads 推荐的。单个任务最多提交 200 个，最多可获取 3000 条建议。

该接口采用标准任务模式：提交任务后，系统异步采集数据，随后通过任务查询接口获取结果。任务执行时间取决于系统负载。如果业务需要实时返回结果，可使用 Live 接口：

POST /v3/keywords_data/bing/keywords_for_keywords/live

历史数据最长可查询近 24 个月。

接口信息

请求方法： POST
请求路径： /v3/keywords_data/bing/keywords_for_keywords/task_post
完整 URL： https://api.seermartech.cn/v3/keywords_data/bing/keywords_for_keywords/task_post
请求格式： application/json
认证方式： Authorization: Bearer smt_live_YOUR_KEY

计费说明

提交任务时计费，查询任务结果不重复计费。

参考价约 ¥0.36 / 个任务（示例响应中的 0.05 美按参考汇率换算供说明）；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制

平台限流以认证说明中的 30/60/120 次/分钟规则为准。

每次 POST 请求最多 100 个任务。 -过 100 个任务的部分将返回错误码 40006。
每个任务最多 200 个。
每个长度不得 100 个字符。
所有 POST 数据使用 UTF-8 编码的 JSON 格式。
请求体是 JSON 数组，即使只提交一个任务也需要使用数组格式。

任务创建成功后，可通过返回的任务 id 查询结果。也可以在请求中 postback_url 或 pingback_url，由本平台在任务完成后主动通知。

如果回调服务器在 10 秒未返回响应，连接将因时中断，任务会转 tasks_ready 列表。

请求参数

请求体为任务对象数组，每个对象代表一个任务。

参数	类型	填	说明
`keywords`	array	是	用于获取的种子数组。每个任务最多 200 个，每个最多 100 个字符。系统会将转换为小写，并在结果中单独返回。
`location_name`	string	条件填	搜索引擎地域的完整名称。未指定 `location_code` 或 `location_coordinate` 时填。使用此参数后，无需再传另外两个地域参数。示例：`London,England,United Kingdom`
`location_code`	integer	条件填	搜索引擎地域代码。未指定 `location_name` 或 `location_coordinate` 时填。示例：`2840`
`location_coordinate`	string	条件填	地域 GPS 坐标，格式为 `"纬度,经度"`，例如 `52.6178549,-155.352142`。返回数据将对应坐标所属国家。使用此参数后，无需再传 `location_name` 或 `location_code`。
`language_name`	string	条件填	搜索引擎语言名称。未指定 `language_code` 时填。支持：`English`、`French`、`German`。
`language_code`	string	条件填	搜索引擎语言代码。未指定 `language_name` 时填。支持：`en`、`fr`、`de`。
`sort_by`	string	否	结果排序字段，支持 `search_volume`、`cpc`、`competition`、`relevance`。结果按降序排列。默认值：`relevance`。
`keywords_negative`	array	否	需要从结果中排除的数组，最多 200 个。系统会将转换为小写。
`device`	string	否	设备类型。可选值：`all`、`mobile`、`desktop`、`tablet`。默认值：`all`。
`date_from`	string	否	数据起始日期，格式为 `yyyy-mm-dd`。如果不指定，默认返回最近 12 个月的数据。可查询范围最长为近 24 个月。
`date_to`	string	否	数据结束日期，格式为 `yyyy-mm-dd`。如果不指定，默认返回最近 12 个月的数据。最大可设置为当前日期前一个月，最早可追溯至两年前。
`search_partners`	boolean	否	是否 Bing 搜索合作伙伴网络。设置为 `true` 时， Bing、Yahoo、AOL 及托管搜索网络的合作伙伴站点。默认值：`false`，返回 Bing、AOL 和 Yahoo 搜索网络数据。
`postback_url`	string	否	任务完成后，本平台向该地址发送结果的 POST 请求。请求使用 gzip 压缩。支持在 URL 中使用 `$id` 和 `$tag` 占位符。
`pingback_url`	string	否	任务完成后，本平台向该地址发送 GET 请求进行通知。支持在 URL 中使用 `$id` 和 `$tag` 占位符。
`tag`	string	否	自定义任务标识，最长 255 个字符。可用于任务与业务数据，提交的值会原样返回在响应的 `data` 对象中。

地域参数说明

location_name、location_code 和 location_coordinate 三只能选择一个。

可通过以下接口获取 Bing 支持的地域列表：

GET /v3/keywords_data/bing/locations

日期参数说明

未指定 date_from 和 date_to 时，默认返回最近 12 个月数据。
当状态接口 /v3/keywords_data/bing/status/ 返回的 actual_data 为 false 时，date_from 最多只能设置为上上个月及更早日期。
当 actual_data 为 true 时，date_from 可设置为上个月及更早日期。
对过去一年的数据，不建议使用自定义日期范围。

cURL 示例

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/bing/keywords_for_keywords/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",
        "adsense blank ads how long",
        "leads and prospects"
      ],
      "sort_by": "relevance",
      "device": "all",
      "tag": "keyword-expansion-demo"
    }
  ]'

Python 示例

python

import requests

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

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

# 请求体是 JSON 数组
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keywords": [
            "average page rpm adsense",
            "adsense blank ads how long",
            "leads and prospects",
        ],
        "keywords_negative": ["free"],
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
    }
]

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

result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：{}，错误信息：{}".format(
            result.get("status_code"),
            result.get("status_message"),
        )
    )

TypeScript 示例

typescript

import axios from "axios";

const payload = [
  {
    language_code: "en",
    location_code: 2840,
    keywords: [
      "average page rpm adsense",
      "adsense blank ads how long",
      "leads and prospects",
    ],
    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/keywords_for_keywords/task_post",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log("任务提交成功：", result);
    } else {
      console.error(
        `请求失败，错误码：${result.status_code}，错误信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络或接口请求异常：", error.message);
  });

回调通知

`pingback_url`

任务完成后，本平台向指定地址发送 GET 请求。例如：

text

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

：

$id 会被替换为任务 ID。
$tag 会被替换为经过 URL 编码的任务标签。

`postback_url`

任务完成后，本平台向指定地址发送 POST 请求，并在请求体中发送 gzip 压缩后的任务结果。例如：

text

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

：

$id 会被替换为任务 ID。
$tag 会被替换为经过 URL 编码的任务标签。
URL 中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。
回调服务器应在 10 秒返回响应，否则连接会时，任务将转 tasks_ready 列表。

响应字段

接口返回 JSON 对象 tasks 数组。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。完整错误码请参考错误码文档。
`status_message`	string	请求级状态信息。
`time`	string	请求执行耗时，例如 `0.0917 sec.`。
`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` 数组中的数量。任务刚提交时通常为 `0`。
`path`	array	当前 API 请求路径信息。
`data`	object	创建任务时提交的参数。
`result`	array \| null	任务结果数组。使用标准任务模式创建任务后，提交响应中的值为 `null`，需要通过任务查询接口获取结果。

响应示例

json

{
  "version": "0.1.20200923",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0917 sec.",
  "cost": 0.36,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0123 sec.",
      "cost": 0.36,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "keywords_for_keywords",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "keywords_for_keywords",
        "se": "bing",
        "location_code": 2840,
        "language_code": "en",
        "keywords": [
          "average page rpm adsense",
          "adsense blank ads how long",
          "leads and prospects"
        ]
      },
      "result": null
    }
  ]
}

错误处理

请根据顶层 status_code、任务级 status_code 及对应的 status_message 判断请求和任务是否成功。

常见：

20000：请求成功。
40006：单次请求中的任务数量 100 个。
任务级状态码非成功状态：任务创建或处理失败，应结合 status_message 进行排查。

建议在客户端实现以下处理机制：

检查 HTTP 状态码和 JSON 中的 status_code。
分别统计 tasks_error 和每个任务的状态码。
保存任务 id，用于后续查询或失败重试。
对回调时、网络异常和服务端错误进行重试控制。
以响应头 X-SeerMarTech-Charge-CNY 记录扣费金额。

实用场景

扩展种子：根据核心词批量获取 Bing ，扩大 SEO选题和覆盖范围。
筛选区域：结合地域名称、地域代码或坐标获取本地化建议，支持多地区 SEO 规划。
比较设备搜索需求：分别提交移动端、桌面端和平板端任务，识别不同设备用户的搜索偏好。
排除无效词项：使用 keywords_negative 过滤品牌无词、类词或低价值词，提升分析效率。
回传任务结果：通过 postback_url 或 pingback_url 自动通知业务系统，减少轮询并加快生产、广告投放和报表更新流程。

设置扩展任务 ​

接口信息 ​

计费说明 ​

请求限制 ​

请求参数 ​

地域参数说明 ​

日期参数说明 ​

cURL 示例 ​

Python 示例 ​

TypeScript 示例 ​

回调通知 ​

pingback_url ​

postback_url ​

响应字段 ​

顶层响应字段 ​

tasks 数组中的任务字段 ​

响应示例 ​

错误处理 ​

实用场景 ​