获取 Bing 效果数据任务结果

本接口使用 GET 方法，通过任务 ID 获取 Bing 效果数据：

GET https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/task_get/$id

根据任务提交时指定的匹类型、地域和语言，接口会返回一组的效果指标。数据按分别返回，并可按设备类型聚合移动设备、桌面设备和平板设备。指标通常统计最近一个月的数据广告位置、点击次数、展示次数、点击率和平均点击成本等。

使用限制与计费

任务提交操作会产生费用。
任务完成后，可在 30 天多次获取结果，获取结果本身不额外收费。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

接口通过 URL 路径接收任务 ID，无需请求体。

参数	类型	填	说明
`id`	string	是	任务唯一标识，UUID 格式。任务提交成功后，可在 30 天使用该 ID 获取任务结果。

请求示例

cURL

bash

task_id="10261501-0696-0254-0000-6f03c275b8de"

curl --location --request GET \
  "https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/task_get/${task_id}" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

TypeScript

typescript

import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios
  .get(
    `https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/task_get/${taskId}`,
    {
      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);
  });

Python

python

import requests

task_id = "10261501-0696-0254-0000-6f03c275b8de"
url = (
    "https://api.seermartech.cn/v3/keywords_data/bing/"
    f"keyword_performance/task_get/{task_id}"
)

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
)

if response.ok:
    result = response.json()
    print(result)
else:
    print(f"请求失败：HTTP {response.status_code}，{response.text}")

响应结构

服务器返回 JSON 数据，顶层 tasks 数组。每个任务对象任务状态、费用、请求参数和结果数据。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用响应状态码。完整错误码请参考错误码文档。
`status_message`	string	通用状态说明。
`time`	string	请求执行耗时，例如 `0.0653 sec.`。
`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	效果结果数组。

`data` 字段

data 字段创建任务时提交的参数，例如：

字段	类型	说明
`api`	string	API 模块名称，例如 `keywords_data`。
`function`	string	功能名称，例如 `keyword_performance`。
`se`	string	搜索引擎名称，此接口为 `bing`。
`location_code`	integer	地域代码。
`language_code`	string	语言代码。
`match`	string	匹类型。
`keywords`	array	提交查询的数组。

`result` 字段

result 数组中的每个对应一个。

字段	类型	说明
`keyword`	string	查询。
`location_code`	integer \| null	对应的地域代码。无数据时为 `null`。
`language_code`	string \| null	对应的语言代码。无数据时为 `null`。
`year`	integer	数据所属年份。
`month`	integer	数据所属月份。
`keyword_kpi`	object \| null	效果指标。无数据时为 `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": "0.0653 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "10261501-0696-0254-0000-6f03c275b8de",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0412 sec.",
      "cost": 0,
      "result_count": 2,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "keyword_performance",
        "task_get"
      ],
      "data": {
        "api": "keywords_data",
        "function": "keyword_performance",
        "se": "bing",
        "location_code": 2840,
        "language_code": "en",
        "match": "broad",
        "keywords": [
          "seo",
          "keyword research"
        ]
      },
      "result": [
        {
          "keyword": "keyword research",
          "location_code": 2840,
          "language_code": "en",
          "year": 2020,
          "month": 9,
          "keyword_kpi": {
            "desktop": [
              {
                "ad_position": "MainLine1",
                "clicks": 120,
                "impressions": 2400,
                "average_cpc": 3,
                "ctr": 5,
                "total_cost": 360,
                "average_bid": 4
              }
            ],
            "mobile": null,
            "tablet": null
          }
        },
        {
          "keyword": "seo",
          "location_code": 2840,
          "language_code": "en",
          "year": 2020,
          "month": 9,
          "keyword_kpi": {
            "desktop": [],
            "mobile": [],
            "tablet": []
          }
        }
      ]
    }
  ]
}

错误处理

建议根据顶层响应和任务级响应分别处理异常：

检查顶层 status_code。
再检查 tasks[].status_code。
当任务级 status_code 表示失败，或 result 为空时，应读取对应的 status_message。
对 keyword_kpi、desktop、mobile 和 tablet 的 null 值进行容处理，将无数据误判为请求失败。

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

实用场景

对比桌面、移动和平板设备的广告表现，识别不同设备上的流量和转化机会，优化分设备投放策略。
分析的点击率、展示量和平均点击成本，筛选高低点击或高点击高成本，提升广告预算使用效率。
评估不同广告位置的点击效果，比较 MainLine 与 FirstPage 位置的表现，为出价和排名策略提供依据。
按地域、语言和匹类型拆分数据，定位特定市场中的高价值搜索词，支持区域化 SEO 与 SEM 规划。
结合历史任务结果构建月度监控报表，持续跟踪成本、点击和展示变化，及时发现投放效果波动。

获取 Bing 效果数据任务结果 ​

使用限制与计费 ​

请求参数 ​

请求示例 ​

cURL ​

TypeScript ​

Python ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

data 字段 ​

result 字段 ​

keyword_kpi 设备指标 ​

ad_position 可选值 ​

响应示例 ​

错误处理 ​

实用场景 ​