SeerMarTech API 文档

主题

获取 Bing Keyword Performance 任务结果 ​

通过本接口可按任务 id 获取 Bing 效果数据结果。 返回基于创建任务时指定的、匹类型、地区和语言，提供最近一个月聚合的广告表现指标广告位次、点击量、展示量、平均 CPC、CTR、总花费、平均出价等。

系统会对 POST 提交数组中的每个分别返回结果；并可按设备类型拆分为 mobile、desktop、tablet。

接口说明 ​

  • 请求方式：GET
  • 请求地址：https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/task_get/$id

计费说明 ​

该类接口在创建任务时扣费，任务结果在任务创建后的 30 天 可获取。

  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
  • 本接口获取结果本身通常不额外收费，因此示例中 cost 可能为 0

路径参数 ​

字段名类型说明
idstring任务唯一标识，UUID 格式。可在任务创建后的 30 天 用于随时获取结果。

返回结构 ​

接口返回 JSON 数据，顶层 tasks 数组，每个任务对象对应一次任务结果。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger接口通用状态码，完整列表参考 /v3/appendix/errors
status_messagestring接口通用状态信息
timestring执行耗时，单位秒
costfloat本次请求总成本，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务结果数组

tasks 数组字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态信息
timestring任务执行耗时，单位秒
costfloat当前任务成本，单位 USD
result_countintegerresult 数组中的数量
patharray请求路径
dataobject与创建任务时一致的请求参数
resultarray效果结果数组

data 对象字段 ​

字段名类型说明
apistringAPI 模块名
functionstring功能名
sestring搜索引擎，当前为 bing
location_codeinteger创建任务时指定的地区编码
language_codestring创建任务时指定的语言编码
matchstring创建任务时指定的匹方式
keywordsarray创建任务时的列表

result 数组字段 ​

字段名类型说明
keywordstringPOST 数组中提交的
location_codeintegerPOST 数组中提交的地区编码；无数据时为 null
language_codestringPOST 数组中提交的语言编码；无数据时为 null
yearinteger数据所属年份，例如 2020
monthinteger数据所属月份，例如 10
keyword_kpiobject效果指标对象；无数据时为 null

keyword_kpi 结构 ​

keyword_kpi 会按设备类型拆分返回：

  • desktop：桌面设备汇总数据
  • mobile：移动设备汇总数据
  • tablet：平板设备汇总数据

若某设备无数据，则该字段为 null。

设备维度字段说明 ​

以下字段适用于 desktop、mobile、tablet 三类设备对象。

字段名类型说明
ad_positionstring广告在搜索结果中的展示位置
clicksinteger广告点击量，即该及匹方式在最近一个月带来的点击数
impressionsinteger广告展示量，即该及匹方式在最近一个月产生的展示次数
average_cpcinteger平均每次点击成本，单位 USD；由总点击成本除以点击次数计算
ctrinteger点击率（百分比）；按点击量 ÷ 展示量 × 100 计算
total_costinteger最近一个月该及匹方式的总花费，单位 USD
average_bidinteger平均出价

ad_position 可选值 ​

首页右侧广告位 ​

  • FirstPage1：搜索结果第一页右侧第 1 个广告位
  • FirstPage2：搜索结果第一页右侧第 2 个广告位
  • FirstPage3：搜索结果第一页右侧第 3 个广告位
  • FirstPage4：搜索结果第一页右侧第 4 个广告位
  • FirstPage5：搜索结果第一页右侧第 5 个广告位
  • FirstPage6：搜索结果第一页右侧第 6 个广告位
  • FirstPage7：搜索结果第一页右侧第 7 个广告位
  • FirstPage8：搜索结果第一页右侧第 8 个广告位
  • FirstPage9：搜索结果第一页右侧第 9 个广告位
  • FirstPage10：搜索结果第一页右侧第 10 个广告位

顶部主广告位 ​

  • MainLine1：搜索结果顶部第 1 个广告位
  • MainLine2：搜索结果顶部第 2 个广告位
  • MainLine3：搜索结果顶部第 3 个广告位
  • MainLine4：搜索结果顶部第 4 个广告位

调用示例 ​

cURL ​

bash
id="10261501-0696-0254-0000-6f03c275b8de"

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

Python ​

python
import requests

task_id = "02231934-2604-0066-2000-570459f04879"
url = f"https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/task_get/{task_id}"

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

response = requests.get(url, headers=headers)
data = response.json

print(data)

TypeScript ​

typescript
import axios from "axios";

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

axios({
 method: "get",
 url: `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);
 });

结合 tasks_ready 获取已完成任务 ​

使用中，通常通过 /v3/keywords_data/bing/keyword_performance/tasks_ready 拉取已完成任务列表，再按返回的任务 id 或 endpoint 调用本接口获取明细结果。

Python 示例：获取已完成任务，再获取结果 ​

python
import requests

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

# 1. 获取已完成任务列表
ready_url = "https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/tasks_ready"
ready_resp = requests.get(ready_url, headers=headers)
ready_data = ready_resp.json

results = []

if ready_data.get("status_code") == 20000:
 for task in ready_data.get("tasks", []):
 for item in task.get("result", []) or []:
 # 2. 按 endpoint 获取结果
 endpoint = item.get("endpoint")
 if endpoint:
 result_resp = requests.get(f"https://api.seermartech.cn{endpoint}", headers=headers)
 results.append(result_resp.json)

 # 3. 或按 id 手动拼接 task_get 地址
 # task_id = item.get("id")
 # if task_id:
 # result_url = f"https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/task_get/{task_id}"
 # result_resp = requests.get(result_url, headers=headers)
 # results.append(result_resp.json)

print(results)

响应示例 ​

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": "02231934-2604-0066-2000-570459f04879",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0312 sec.",
 "cost": 0,
 "result_count": 2,
 "path": [
 "v3",
 "keywords_data",
 "bing",
 "keyword_performance",
 "task_get",
 "02231934-2604-0066-2000-570459f04879"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keyword_performance",
 "se": "bing",
 "location_code": 2840,
 "language_code": "en",
 "match": "broad",
 "keywords": [
 "search engine optimization",
 "seo"
 ]
 },
 "result": [
 {
 "keyword": "search engine optimization",
 "location_code": 2840,
 "language_code": "en",
 "year": 2020,
 "month": 9,
 "keyword_kpi": {
 "desktop": {
 "ad_position": "MainLine1",
 "clicks": 120,
 "impressions": 2400,
 "average_cpc": 2,
 "ctr": 5,
 "total_cost": 240,
 "average_bid": 3
 },
 "mobile": null,
 "tablet": null
 }
 },
 {
 "keyword": "seo",
 "location_code": 2840,
 "language_code": "en",
 "year": 2020,
 "month": 9,
 "keyword_kpi": {
 "desktop": {
 "ad_position": "MainLine2",
 "clicks": 80,
 "impressions": 1900,
 "average_cpc": 1,
 "ctr": 4,
 "total_cost": 80,
 "average_bid": 2
 },
 "mobile": {
 "ad_position": "MainLine1",
 "clicks": 60,
 "impressions": 1500,
 "average_cpc": 1,
 "ctr": 4,
 "total_cost": 60,
 "average_bid": 2
 },
 "tablet": null
 }
 }
 ]
 }
 ]
}

错误处理建议 ​

  • 顶层 status_code 用于判断接口请求是否成功
  • tasks[].status_code 用于判断任务是否成功
  • 建议同时处理以下异常：
  • 请求成功但任务未完成
  • 任务存在但 result 为空
  • 某些无数据，导致 location_code、language_code 或 keyword_kpi 为 null
  • 某些设备维度无数据，导致 desktop、mobile、tablet 为 null

完整错误码与状态信息请参考 /v3/appendix/errors。

实用场景 ​

  • 回查投放效果：按任务 ID 拉取 Bing 广告效果结果，快速核对某批的点击、展示与花费表现。
  • 拆分设备表现：分别分析桌面端、移动端、平板端的 KPI，帮助优化不同设备上的出价和投放策略。
  • 评估广告位价值：结合 ad_position、ctr 和 average_cpc 判断顶部广告位与侧边广告位的流量质量差异。
  • 筛选高成本低回报词：利用 total_cost、clicks、impressions 等指标识别花费高但点击率低的，减少预算浪费。
  • 构建月度报告：按 year、month 汇总任务结果，为 SEO/SEM 团队生成效果复盘报表。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API