Bing 广告受众预估（实时）

接口概述

该接口用于根据指定的广告定向条件，预估 Bing 广告活动可触达的受众规模，并返回投放参考数据：

• 预估受众总量
• 预估展示量
• 预估点击量
• 预估花费
• 建议出价
• 建议预算
• 预估点击率等

如果你的业务需要实时返回结果，推荐使用本接口的 Live 方法。与标准任务模式不同，Live 方法无需拆分为单独的 POST 与 GET 请求，一次调用即可直接获得结果。

如果不要求实时返回，也可以使用标准任务模式进行数据获取。标准模式通常更经济，但需要创建任务，再获取结果。

请求方式

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

计费说明

该接口按请求计费。

参考价约 ¥1.2000 / 次。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用说明

• 请求体使用 JSON（UTF-8 编码）
• POST 请求体格式为 JSON 数组：[{ ... }]
• 每分钟最多可发送 2000 次 API 调用

---

请求参数

以下为可用于设置任务的字段说明。

字段名	类型	说明
location_name	string	搜索引擎地域的完整名称。若未提供 location_code 或 location_coordinate，则该字段填。使用该字段时，无需再传 location_code 或 location_coordinate。可通过 /v3/keywords_data/bing/locations 获取可用地域及 location_name。示例：London,England,United Kingdom
location_code	integer	搜索引擎地域编码。若未提供 location_name 或 location_coordinate，则该字段填。使用该字段时，无需再传 location_name 或 location_coordinate。可通过 /v3/keywords_data/bing/locations 获取可用地域及 location_code。示例：2840
location_coordinate	string	地理坐标位置。若未提供 location_name 或 location_code，则该字段填。使用该字段时，无需再传 location_name 或 location_code。格式为：latitude,longitude,radius_in_km。系统将返回该坐标所属国家的数据。示例：29.6821525,-82.4098881,100
age	array	年龄定向范围。可选值：eighteen_to_twenty_four、fifty_to_sixty_four、sixty_five_and_above、thirteen_to_seventeen、thirty_five_to_forty_nine、twenty_five_to_thirty_four、unknown、zero_to_twelve
bid	float	期望出价值，单位为 USD。最大值：1000
daily_budget	float	广告系列每日预算，单位为 USD。最大值：10000
gender	array	性别定向。可选值：male、female、unknown
industry	array	LinkedIn 档案行业定向。使用该字段时，可通过 /v3/keywords_data/bing/audience_estimation/industries 获取可用行业名称及 industry_id。示例：806301758
job_function	array	LinkedIn 档案职能定向。使用该字段时，可通过 /v3/keywords_data/bing/audience_estimation/job_functions 获取可用职能名称及 job_function_id。示例：806300451

---

响应结构

接口返回 JSON 编码数据，顶层 tasks 数组，每个任务对应一次提交的数据及结果。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码。完整错误码请参考 /v3/appendix/errors
status_message	string	通用状态信息。完整信息请参考 /v3/appendix/errors
time	string	执行时间，单位秒
cost	float	本次请求所有任务总成本，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务结果数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行时间，单位秒
cost	float	当前任务成本，单位 USD
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	回显你在请求中提交的参数
result	array	结果数组

result[] 字段

字段名	类型	说明
est_impressions	object	月预估展示量区间
est_impressions.high	integer	区间上限
est_impressions.low	integer	区间下限
est_audience_size	object	月预估可触达用户数区间
est_audience_size.high	integer	区间上限
est_audience_size.low	integer	区间下限
est_clicks	object	月预估点击量区间
est_clicks.high	integer	区间上限
est_clicks.low	integer	区间下限
est_spend	object	月预估花费区间
est_spend.high	integer	区间上限
est_spend.low	integer	区间下限
est_cost_per_event	object	预估单次事件成本区间
est_cost_per_event.high	float	区间上限
est_cost_per_event.low	float	区间下限
est_ctr	object	预估点击率区间
est_ctr.high	float	区间上限
est_ctr.low	float	区间下限
suggested_bid	float	当前定向条件下的建议出价
suggested_budget	integer	当前定向条件与出价下的建议日预算
events_lost_to_bid	integer	因出价不足而损失的事件数量
events_lost_to_budget	integer	因预算不足而损失的事件数量
est_reach_audience_size	integer	月预估触达用户数
est_reach_impressions	integer	月预估展示量
currency	integer	币种名称。示例：USDollar

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_coordinate": "29.6821525,-82.4098881,100",
 "age": ["twenty_five_to_thirty_four", "thirty_five_to_forty_nine"],
 "bid": 1,
 "daily_budget": 24,
 "gender": ["male"],
 "industry": [806301758],
 "job_function": [806300451]
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "location_code": 2840,
 "bid": 10
 }
]

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

TypeScript

const response = await fetch("https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/live", {
 method: "POST",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 body: JSON.stringify([
 {
 location_code: 2840,
 bid: 10
 }
 ])
});

const data = await response.json;
console.log(data);

---

响应示例

{
 "version": "0.1.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "12.1899 sec.",
 "cost": 0.075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "audience_estimation",
 "se": "bing",
 "location_coordinate": "29.6821525,-82.4098881,100",
 "age": ["twenty_five_to_thirty_four", "thirty_five_to_forty_nine"],
 "bid": 1,
 "daily_budget": 24,
 "gender": ["male"],
 "industry": [806301758],
 "job_function": [806300451]
 },
 "result": []
 }
 ]
}

---

状态码与异常处理

• 顶层 status_code 表示整个请求的处理状态
• tasks[].status_code 表示单个任务的执行状态
• 建议同时检查：
• 顶层 status_code
• tasks_error
• 每个任务的 status_code
• result_count

常见成功状态：

状态码	含义
20000	请求成功

完整错误码及说明请参考 /v3/appendix/errors。 建议在生产环境中设计完善的异常处理机制，例如：

• 请求参数校验失败
• 地域参数缺失或冲突
• 频率限制触发
• 单任务执行失败但整体请求成功
• 返回结果为空

---

使用建议

1. location_name、location_code、location_coordinate 三至少传一个
2. 如果已传任一地域字段，不要再重复传另外两个，以产生歧义
3. industry 与 job_function 适用于更细粒度的人群定向预估
4. bid 和 daily_budget 会直接影响建议值与流量损失指标
5. 若要批量评估不同定向组合，可在一个请求中传多个任务对象（仍需遵守频率限制）

实用场景

• 评估广告定向规模：在正式投放前快速估算某地区、年龄、性别、行业组合下的可触达人群，降低试错成本。
• 优化出价策略：根据 suggested_bid、events_lost_to_bid 判断当前出价是否过低，提高预算利用效率。
• 控制预算分：结合 suggested_budget 与 events_lost_to_budget 评估预算是否足，为多广告组分日预算提供依据。
• 筛选高潜力受众：对多个行业、职能组合做横向比较，优选择点击量和触达规模更优的人群。
• 生成投放预案：基于预估展示、点击、CTR 和花费区间，提前输出媒体投放预测报表，销售或运营决策。