设置 Bing URL 建议任务

本接口使用 POST 方法创建 Bing URL 建议任务：

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

接口会分析指定网页的，并返回及置信度信息，用于判断与用户搜索意图的匹概率。

本接口采用标准任务模式：提交任务后，系统会异步处理。任务完成后，可以通过任务 ID 获取结果；如果需要实时返回结果，请使用对应的 Live 接口。任务执行时间取决于系统负载。

计费说明

提交任务时计费，任务后续查询通常不重复计费。

示例响应中的原始任务费用为 0.05，按参考汇率换算，参考价约 ¥0.36 / 次。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制

请求体使用 UTF-8 编码的 JSON 格式。
请求体是 JSON 数组，格式为 [{ ... }]。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
每次 POST 请求最多 100 个任务。 -过 100 个任务的部分会返回错误码 40006。
建议根据任务量控制请求频率，并实现错误重试与异常处理机制。

任务提交后，可以通过任务唯一标识 id 查询结果。也可以在创建任务时设置 postback_url 或 pingback_url，任务完成后由本平台主动推送结果。

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

请求参数

任务参数

每个任务对象应放在 POST 请求体数组中。

参数	类型	填	说明
`target`	string	是	要扫描并分析的网页 URL。最大长度为 2000 个字符。
`language_name`	string	条件填	搜索引擎语言的完整名称。未指定 `language_code` 时填。指定此字段后，无需再传 `language_code`。
`language_code`	string	条件填	搜索引擎语言代码。未指定 `language_name` 时填。指定此字段后，无需再传 `language_name`。
`exclude_brands`	boolean	否	是否排除品牌。`true` 表示排除，`false` 表示不排除。

language_name 和 language_code 二选一即可。可通过以下接口获取 Bing 支持的语言列表：

GET https://api.seermartech.cn/v3/keywords_data/bing/keyword_suggestions_for_url/languages

示例：

language_name：English
language_code：en

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/bing/keyword_suggestions_for_url/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": "https://example.com/page",
      "language_code": "en",
      "exclude_brands": true
    }
  ]'

Python

python

import requests

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

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

# 请求体是 JSON 数组
payload = [
    {
        "target": "https://example.com/page",
        "language_code": "en",
        "exclude_brands": True,
    }
]

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

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        "请求失败，错误码：%s，错误信息：%s"
        % (data.get("status_code"), data.get("status_message"))
    )

TypeScript

typescript

const url =
  "https://api.seermartech.cn/v3/keywords_data/bing/keyword_suggestions_for_url/task_post";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    {
      target: "https://example.com/page",
      language_code: "en",
      exclude_brands: true,
    },
  ]),
});

const data = await response.json();

if (data.status_code === 20000) {
  console.log(data);
} else {
  console.error(
    `请求失败，错误码：${data.status_code}，错误信息：${data.status_message}`
  );
}

响应结构

接口返回 JSON 对象 tasks 为已创建任务的数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。完整错误码列表请参考错误码文档。
`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 格式。
`status_code`	integer	任务级状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务级状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求 URL 路径信息。
`data`	object	创建任务时提交的参数。
`result`	array \| null	任务结果数组。创建任务接口返回时通常为 `null`。

成功响应示例

json

{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0657 sec.",
  "cost": 0.36,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "330a3d6e-0000-0000-0000-000000000000",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0123 sec.",
      "cost": 0.36,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "keyword_suggestions_for_url",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "keyword_suggestions_for_url",
        "se": "bing",
        "language_code": "en",
        "target": "https://example.com/page",
        "exclude_brands": true
      },
      "result": null
    }
  ]
}

错误处理

错误码	说明
`20000`	请求成功。
`40006`	单次 POST 请求提交的任务数量 100 个。
错误码	可能表示参数错误、认证失败、任务创建失败或系统异常，请根据 `status_code` 和 `status_message` 进行处理。

建议客户端至少实现以下机制：

检查顶层 status_code 和每个任务的 status_code。
根据 tasks_error 判断是否存在失败任务。
记录任务 id，便于后续查询和问题排查。
对临时性错误执行有限次数的重试。
校验 URL、语言参数和请求体数组格式。

实用场景

分析竞品页面并提取，快速发现竞品覆盖的搜索主题，为差距分析提供依据。
批量扫描落地页并生成建议， SEO 团队扩展页面标题、正文和数据中的目标词。
排除品牌词后评估非品牌搜索机会，帮助企业识别更增长潜力的通用。
按指定语言分析多地区页面，支持化 SEO 项目进行语言市场规划。
通过异步任务批量处理 URL，降低大规模研究的实时接口压力，提高数据采集吞吐量。

设置 Bing URL 建议任务 ​

计费说明 ​

请求限制 ​

请求参数 ​

任务参数 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

成功响应示例 ​

错误处理 ​

实用场景 ​