SeerMarTech API 文档

主题

Bing 表现（实时）接口 ​

接口概述 ​

通过本接口，你可以基于指定的、匹类型、地区和语言，实时获取一组在 Bing 广告中的表现数据。返回指标按最近一个月聚合，支持以下设备维度：

  • mobile
  • desktop
  • tablet
  • all

可返回的核心指标：

  • 广告展示位置 ad_position
  • 点击量 clicks
  • 展示量 impressions
  • 平均点击成本 average_cpc
  • 点击率 ctr
  • 总花费 total_cost
  • 平均出价 average_bid

接口会对你在 POST 数组中提交的每个分别返回结果。

如果你的系统需要实时返回结果，推荐使用 Live 方法；该方法无需像标准任务模式那样分别调用 POST 和 GET 接口。

  • 实时接口：POST /v3/keywords_data/bing/keyword_performance/live
  • 非实时、成本更低的标准模式：/v3/keywords_data/bing/keyword_performance/task_post/

数据更新说明 ​

该数据通常在每月第 3 天后由平台数据源完成更新。

例如：

  • 如果你在 8 月 1 日、2 日或 3 日请求数据，而 7 月数据尚未更新完成，则返回的可能仍是 6 月数据；
  • 当月第 4 天后通常可以获取上一个自然月的数据；
  • 响应 result 数组中的 month 字段表示当前返回数据所属月份。

请求地址 ​

POST https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/live

计费说明 ​

该接口按创建任务计费。

原文未提供固定单价，因此无法给出精确人民币参考价。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制 ​

  • 每分钟最多 2000 次 API 调用
  • 单个 keywords 数组最多可提交 2500 个
  • 但字段定义中 keywords 的最大数量说明为 1000
  • 实接时，建议按 1000 个/次 进行调用，以确保容性

说明：接口按请求计费，而不是按个数计费；同一次请求中提交 1 个或 1000 个，单次请求价格一致。

请求体格式 ​

所有 POST 数据使用 JSON（UTF-8） 格式提交。

请求体为 JSON 数组：

json
[
 {
 "location_name": "United States",
 "language_name": "English",
 "keywords": ["seo", "ranking"]
 }
]

请求参数 ​

字段名类型说明
keywordsarray填。列表。每个最长 80 个字符，最多 10 个单词。系统会自动转为小写。返回结果会按分别输出。字段说明中最大数量为 1000。
devicestring可选。设备类型。可选值：desktop、mobile、tablet、all。默认值：all。
matchstring可选。匹类型。可选值：aggregate、broad、phrase、exact。默认值：aggregate。
location_namestring当未传 location_code 或 location_coordinate 时填。搜索地区完整名称。若使用该字段，则无需传 location_code 或 location_coordinate。示例：United States
location_codeinteger当未传 location_name 或 location_coordinate 时填。搜索地区代码。若使用该字段，则无需传 location_name 或 location_coordinate。示例：2840
location_coordinatestring当未传 location_name 或 location_code 时填。GPS 坐标，格式为 "latitude,longitude"。数据将按该坐标所属国家返回。示例：52.6178549,-155.352142
language_namestring当未传 language_code 时填。搜索语言完整名称。若使用该字段，则无需传 language_code。示例：English
language_codestring当未传 language_name 时填。搜索语言代码。示例：en
tagstring可选。自定义任务标识，最长 255 个字符。可用于在响应中识别和任务。

match 参数说明 ​

值说明
aggregate汇总所有匹类型的数据
broad返回指定关键词、且词序可变化的用户查询数据
phrase返回指定关键词、且词序一致的用户查询数据
exact返回与指定一致的用户查询数据

地区与语言列表 ​

可通过以下接口获取支持的地区和语言列表：

/v3/keywords_data/bing/keyword_performance/locations_and_languages

返回结果说明 ​

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段 ​

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

tasks[] 字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，通常范围 10000-60000，完整列表见 /v3/appendix/errors
status_messagestring任务状态信息
timestring任务执行耗时，单位秒
costfloat当前任务费用，单位 USD
result_countintegerresult 数组数量
patharray请求路径
dataobject与请求体中提交参数一致
resultarray结果数组

result[] 字段 ​

字段名类型说明
keywordstring请求中的
location_codeinteger请求中的地区代码；如无数据则为 null
language_codestring请求中的语言代码；如无数据则为 null
yearinteger数据所属年份，例如 2020
monthinteger数据所属月份，例如 10
keyword_kpiobject指标对象；如无数据则为 null

keyword_kpi 字段 ​

keyword_kpi 下按设备返回聚合数据：

  • desktop
  • mobile
  • tablet

如果某设备无数据，则对应值为 null。

设备指标字段 ​

字段名类型说明
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
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",
 "website audit"
 ],
 "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"
}

payload = [
 {
 "location_name": "United States",
 "language_name": "English",
 "keywords": [
 "seo",
 "ranking",
 "website audit"
 ],
 "device": "all",
 "match": "aggregate",
 "tag": "bing-keyword-performance-demo"
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const payload = [
 {
 location_name: "United States",
 language_name: "English",
 keywords: ["seo", "ranking", "website audit"],
 device: "all",
 match: "aggregate",
 tag: "bing-keyword-performance-demo"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/bing/keyword_performance/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: payload
})
 .then((response) => {
 // 输出返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

响应示例 ​

json
{
 "version": "0.1.20201021",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "11.8263 sec.",
 "cost": 0.05,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "a7b7c6d1-1234-4567-89ab-1234567890ab",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "11.8263 sec.",
 "cost": 0.05,
 "result_count": 3,
 "path": [
 "v3",
 "keywords_data",
 "bing",
 "keyword_performance",
 "live"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keyword_performance",
 "se": "bing",
 "location_code": 1026218,
 "language_code": "en",
 "keywords": [
 "seo",
 "ranking",
 "website audit"
 ]
 },
 "result": [
 {
 "keyword": "website audit",
 "location_code": 1026218,
 "language_code": "en",
 "year": 2020,
 "month": 9,
 "keyword_kpi": {
 "desktop": {
 "ad_position": "MainLine1",
 "clicks": 120,
 "impressions": 1500,
 "average_cpc": 2,
 "ctr": 8,
 "total_cost": 240,
 "average_bid": 3
 },
 "mobile": null,
 "tablet": null
 }
 },
 {
 "keyword": "seo",
 "location_code": 1026218,
 "language_code": "en",
 "year": 2020,
 "month": 9,
 "keyword_kpi": {
 "desktop": {
 "ad_position": "MainLine2",
 "clicks": 95,
 "impressions": 1320,
 "average_cpc": 1,
 "ctr": 7,
 "total_cost": 95,
 "average_bid": 2
 },
 "mobile": {
 "ad_position": "MainLine1",
 "clicks": 140,
 "impressions": 1800,
 "average_cpc": 1,
 "ctr": 8,
 "total_cost": 140,
 "average_bid": 2
 },
 "tablet": null
 }
 },
 {
 "keyword": "ranking",
 "location_code": 1026218,
 "language_code": "en",
 "year": 2020,
 "month": 9,
 "keyword_kpi": {
 "desktop": {
 "ad_position": "FirstPage1",
 "clicks": 60,
 "impressions": 900,
 "average_cpc": 2,
 "ctr": 6,
 "total_cost": 120,
 "average_bid": 2
 },
 "mobile": {
 "ad_position": "MainLine3",
 "clicks": 88,
 "impressions": 1100,
 "average_cpc": 2,
 "ctr": 8,
 "total_cost": 176,
 "average_bid": 3
 },
 "tablet": {
 "ad_position": "FirstPage2",
 "clicks": 10,
 "impressions": 140,
 "average_cpc": 1,
 "ctr": 7,
 "total_cost": 10,
 "average_bid": 1
 }
 }
 }
 ]
 }
 ]
}

错误处理 ​

请基于 status_code 和 status_message 实现错误处理机制，重点区分：

  • 顶层请求是否成功
  • tasks[] 中每个任务是否成功
  • result 是否为空
  • keyword_kpi 或设备维度数据是否为 null

常见排查方向：

  • keywords 是否为空或出限制
  • location_name / location_code / location_coordinate 是否至少提供一
  • language_name / language_code 是否至少提供一
  • device、match 是否使用了的枚举值
  • 请求体是否为 JSON 数组格式 [{...}]

完整错误码列表参考：

  • /v3/appendix/errors

使用建议 ​

  1. 优使用代码型参数 在稳定生产环境中，建议优使用 location_code 和 language_code，名称解析差异。

  2. 注意规格限制 单个最多 80 个字符、10 个词，建议提交前做洗和截断。

  3. 处理月度更新延迟 月初调用时，注意 year 和 month 字段，误把上上月数据当作上月数据。

  4. 区分无数据与调用失败 某些可能返回成功状态，但 keyword_kpi 或某设备数据为 null，这通常表示该条件下无可用数据，而非接口调用失败。

实用场景 ​

  • 评估投放价值：批量查看最近一个月的点击、展示、CPC 和 CTR，快速判断哪些词适合 Bing 广告投放名单。
  • 比较设备端广告表现：按 desktop、mobile、tablet 分析同一在不同设备上的效果差异，帮助优化出价策略和落地页适。
  • 筛选高性价比：结合 average_cpc、total_cost 和 clicks 找出低成本高流量，提升预算使用效率。
  • 监控广告位表现变化：通过 ad_position 观察主要出现的广告位区间，判断竞争强度和出价是否合理。
  • 构建优级模型：将 Bing 表现数据接评分体系，用于扩展、广告预算分和 SEO/SEM 协同决策。

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

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