Bing 效果实时查询

POST /v3/keywords_data/bing/keyword_performance/live

本接口使用 POST 方法，路径为：

/v3/keywords_data/bing/keyword_performance/live

用于实时获取一组在 Bing 广告中的效果数据。接口会根据指定的匹类型、地域和语言，返回过去一个月的广告排名、点击次数、展示次数及指标，并按桌面端、移动端和平板设备分别汇总。

本接口会为请求体中的每个单独返回结果。若业务需要即时获取结果，建议使用本实时接口；与需要分别提交任务和获取结果的标准方式相比，本接口无需额外发起 GET 请求，但单次调用支持一个任务。

> 注意：建议调用 Bing 状态接口，确认 Bing 是否已更新上一个月的数据：
> /v3/keywords_data/bing/status

请求信息

请求方法：POST
请求地址：https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/live
Content-Type：application/json
请求体格式：JSON 数组
单次请求任务数：1 个平台限流以认证说明中的 30/60/120 次/分钟规则为准/分钟
数量：单个 keywords 数组最多 1000 个
计费方式：按请求计费，与请求中数量无；提交 1 个或 1000 个的单次请求价格相同

参考价格

参考价约 ¥0.36 / 次。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体是数组，每个数组代表一个任务。本接口单次调用只能提交一个任务。

参数	类型	填	说明
`keywords`	array	是	要查询的列表。最多 1000 个；每个最多 80 个字符、最多 10 个单词。会被转换为小写，并在结果中分别返回。
`device`	string	否	设备类型。可选值：`desktop`、`mobile`、`tablet`、`all`。默认值为 `all`。
`match`	string	否	匹类型。可选值：`aggregate`、`broad`、`phrase`、`exact`。默认值为 `aggregate`。
`location_name`	string	条件填	搜索引擎地域的完整名称。未指定 `location_code` 或 `location_coordinate` 时填。使用此字段后，无需同时传另外两个地域参数。
`location_code`	integer	条件填	搜索引擎地域代码。未指定 `location_name` 或 `location_coordinate` 时填。
`location_coordinate`	string	条件填	地理坐标，格式为 `"纬度,经度"`。数据将按该坐标所属国家返回。未指定 `location_name` 或 `location_code` 时填。
`language_name`	string	条件填	搜索引擎语言的完整名称。未指定 `language_code` 时填。
`language_code`	string	条件填	搜索引擎语言代码。未指定 `language_name` 时填。
`tag`	string	否	自定义任务标识，最多 255 个字符。可用于请求和响应，提交的值会原样返回在响应的 `data` 对象中。

可通过以下接口查询可用的地域和语言：

https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/locations_and_languages

`keywords`

最大数量：1000 个
单个最大长度：80 个字符
单个短语最多：10 个单词
会自动转换为小写
每个会在结果数组中单独返回

`device`

值	说明
`desktop`	返回桌面端数据
`mobile`	返回移动端数据
`tablet`	返回平板端数据
`all`	返回设备类型数据，默认值

`match`

值	说明
`aggregate`	汇总所有匹类型的数据，默认值
`broad`	返回指定、词序可不同的用户查询数据
`phrase`	返回指定且词序一致的用户查询数据
`exact`	返回与指定匹的用户查询数据

地域参数

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

示例：

location_name："United States"
location_code：2840
location_coordinate："52.6178549,-155.352142"

语言参数

language_name 和 language_code 二只能选择一个。

示例：

language_name："English"
language_code："en"

请求示例

cURL

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/live"

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

post_data = [
    {
        "location_name": "United States",
        "language_name": "English",
        "keywords": [
            "seo",
            "ranking",
        ],
        "device": "all",
        "match": "aggregate",
    }
]

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

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

TypeScript

typescript

import axios from "axios";

const postData = [
  {
    location_name: "United States",
    language_name: "English",
    keywords: ["seo", "ranking"],
    device: "all",
    match: "aggregate",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/live",
    postData,
    {
      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 对象 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。`20000` 表示请求成功。
`status_message`	string	通用状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`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	请求路径信息。
`data`	object	请求中提交的参数。
`result`	array	效果结果数组。

完整错误码请参考错误码文档。

`result` 数组字段

字段	类型	说明
`keyword`	string	请求中的。
`location_code`	integer	请求中的地域代码。无数据时为 `null`。
`language_code`	string	请求中的语言代码。无数据时为 `null`。
`year`	integer	数据所属年份，例如 `2020`。
`month`	integer	数据所属月份，例如 `10`。
`keyword_kpi`	object	指标对象。无数据时为 `null`。

`keyword_kpi` 字段

keyword_kpi 按设备类型分别返回数据：

字段	类型	说明
`desktop`	array 或 null	桌面端数据。无数据时为 `null`。
`mobile`	array 或 null	移动端数据。无数据时为 `null`。
`tablet`	array 或 null	平板端数据。无数据时为 `null`。

每种设备类型数组中的字段结构相同。

字段	类型	说明
`ad_position`	string	广告在搜索结果页中的位置。
`clicks`	integer	过去一个月，该及匹类型产生的广告点击次数。
`impressions`	integer	过去一个月，该及匹类型产生的广告展示次数。
`average_cpc`	integer	平均每次点击费用。按所有点击总成本除以点击次数计算。
`ctr`	integer	点击率百分比。按点击次数除以展示次数，再乘以 100 计算。
`total_cost`	integer	过去一个月使用指定及匹类型产生的广告总成本。
`average_bid`	integer	平均出价。

`ad_position` 可选值

值	说明
`FirstPage1` 至 `FirstPage10`	搜索结果第一页右侧广告位的第 1 至第 10 个位置。
`MainLine1` 至 `MainLine4`	搜索结果页顶部广告位的第 1 至第 4 个位置。

响应示例

json

{
  "version": "0.1.20201021",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "11.8263 sec.",
  "cost": 0.36,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "6f2c0d2e-6a3d-4c0d-9f9b-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "11.8120 sec.",
      "cost": 0.36,
      "result_count": 2,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "keyword_performance",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "keyword_performance",
        "se": "bing",
        "location_code": 2840,
        "language_code": "en",
        "keywords": [
          "seo",
          "ranking"
        ],
        "device": "all",
        "match": "aggregate"
      },
      "result": [
        {
          "keyword": "seo",
          "location_code": 2840,
          "language_code": "en",
          "year": 2020,
          "month": 9,
          "keyword_kpi": {
            "desktop": [
              {
                "ad_position": "MainLine1",
                "clicks": 120,
                "impressions": 2500,
                "average_cpc": 2,
                "ctr": 4.8,
                "total_cost": 240,
                "average_bid": 2
              }
            ],
            "mobile": null,
            "tablet": null
          }
        },
        {
          "keyword": "ranking",
          "location_code": 2840,
          "language_code": "en",
          "year": 2020,
          "month": 9,
          "keyword_kpi": {
            "desktop": [],
            "mobile": [],
            "tablet": []
          }
        }
      ]
    }
  ]
}

状态码与错误处理

顶层 status_code 和任务级 status_code 均应进行判断。
20000 表示请求成功。
应同时检查 tasks_error，确认是否存在部分任务失败。
当某个或设备类型没有可用数据时，字段可能返回 null 或空数组。
建议在客户端实现异常重试、参数校验和错误日志记录。

实用场景

评估广告表现：按和匹类型统计点击、展示、点击率及成本，为 Bing 广告预算分提供依据。
比较不同设备效果：分别分析桌面端、移动端和平板端的表现，优化移动广告出价和落地页策略。
筛选高价值：结合平均点击价格、总成本和点击量识别高转化潜力，支持 SEO 与付费搜索协同选词。
监控地域与语言市场：针对不同国家、地区和语言提交同一组，比较市场需求和广告竞争程度。
生成月度投放报告：获取上个月的广告指标并按、广告位置和设备汇总，自动生成投放复盘报表。

Bing 效果实时查询 ​

请求信息 ​

参考价格 ​

请求参数 ​

keywords ​

device ​

match ​

地域参数 ​

语言参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 数组字段 ​

keyword_kpi 字段 ​

ad_position 可选值 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​