设置 Bing「网站」任务

POST /v3/keywords_data/bing/keywords_for_site/task_post

接口说明

POST /v3/keywords_data/bing/keywords_for_site/task_post

本接口用于提交网站挖掘任务。任务完成后，系统会返回与指定网站的，以及以下数据：

最近一个月的搜索量
最多 24 个月的搜索量趋势，用于分析搜索需求变化
当前每次点击费用（CPC）
付费搜索竞争程度

单个任务最多返回 3000 个。

本接口采用标准任务模式：提交任务后，系统完成采集，再通过任务 ID 获取结果。如果业务需要实时返回结果，可使用对应的 Live 接口。历史数据最多支持查询 24 个月。

请求限制与计费

在成功提交任务时计费。
单次请求最多 100 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
如果单次请求 100 个任务，出部分将返回错误码 40006。
无论最终返回 1 个还是 3000 个，单个任务的计费规则相同。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

所有 POST 数据使用 UTF-8 编码的 JSON 格式，并且请求体是 JSON 数组：

http

POST https://api.seermartech.cn/v3/keywords_data/bing/keywords_for_site/task_post
Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

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

日期参数说明

如果不传 date_from 和 date_to，默认返回最近 12 个月的数据。
如果 /v3/keywords_data/bing/status/ 返回的 actual_data 为 false，date_from 可设置为上上个月及更早日期。
如果 actual_data 为 true，date_from 可设置为上个月及更早日期。
对过去一年的数据，不建议使用自定义日期范围，以数据覆盖范围或完整性受到影响。

回调地址说明

postback_url 和 pingback_url 支持以下占位符：

$id：任务完成后替换为任务 ID。
$tag：任务完成后替换为经过 URL 编码的任务标签。

示例：

text

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

回调地址中的特殊字符会进行 URL 编码，例如 # 会编码为 %23>。如果接收服务器在 10 秒未响应，连接将因时中止，任务会转任务就绪列表。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/bing/keywords_for_site/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "target": "example.com",
      "tag": "site_keywords_001",
      "device": "all",
      "sort_by": "relevance",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    }
  ]'

Python

python

import requests

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

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

# 请求体是 JSON 数组
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "target": "example.com",
        "tag": "site_keywords_001",
        "postback_url": "https://your-server.com/postbackscript?id=$id&tag=$tag",
    }
]

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

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

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    language_code: "en",
    location_code: 2840,
    target: "example.com",
    tag: "site_keywords_001",
    pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
];

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

响应说明

接口返回 JSON 数据已提交任务的信息。由于本接口为异步任务接口，任务提交成功后，任务对象中的 result 通常为 null。任务完成后，可通过任务 ID 获取结果，或回调通知。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。成功时通常为 `20000`。
`status_message`	string	请求级状态信息。
`time`	string	请求执行耗时，例如 `0.0587 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	请求对应的 URL 路径信息。
`data`	object	创建任务时提交的参数。
`result`	array或null	任务结果。任务提交成功但尚未完成时为 `null`。

成功响应示例

json

{
  "version": "0.1.20200923",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0587 sec.",
  "cost": 0.05,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0100 sec.",
      "cost": 0.05,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "keywords_for_site",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "keywords_for_site",
        "se": "bing",
        "language_code": "en",
        "location_code": 2840,
        "target": "example.com"
      },
      "result": null
    }
  ]
}

错误处理

20000：请求成功。
40006：单次请求中的任务数量 100 个，出限制的任务不会被创建。
错误码：请根据顶层或任务级的 status_code 和 status_message 进行处理，并为网络时、回调失败、参数校验失败等设计重试或异常记录机制。

任务创建成功后，可以使用响应中的 id 查询已完成任务；也可以在提交时设置 postback_url 或 pingback_url，由本平台在任务完成后主动通知。

实用场景

挖掘竞品网站：批量分析竞品域名的搜索词、搜索量和 CPC，为差距分析与投放策略制定提供依据。
构建网站库：按国家、语言和设备获取网站，支持 SEO 选词、规划和页面主题聚类。
分析需求趋势：利用最多 24 个月的搜索量历史数据识别季节性需求，制定年度日历。
筛选付费搜索机会：结合 CPC 与竞争程度筛选高商业价值，为搜索广告预算分和落地页优化提供数据支持。
排除无词组：通过 keywords_negative 过滤品牌无词、低转化词或业务不词，提升研究结果的可用性。

设置 Bing「网站」任务 ​

接口说明 ​

请求限制与计费 ​

请求格式 ​

请求参数 ​

日期参数说明 ​

回调地址说明 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks 对象字段 ​

成功响应示例 ​

错误处理 ​

实用场景 ​