获取 Bing 广告受众预估任务结果

接口说明

该接口用于根据任务 id 获取 Bing 广告受众预估任务的结果。

接口会返回指定定向条件下的广告投放预估数据：

• 预计受众规模
• 建议出价
• 建议预算
• 预计、点击、花费等指标
• 因出价或预算不足导致的潜在损失量

适用于在已提交受众预估任务后，按任务 ID 获取结果。

接口地址

GET /v3/keywords_data/bing/audience_estimation/task_get/$id

完整请求地址示例：

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

计费说明

该接口本身不重复计费，在创建任务时扣费。任务创建后，可在 30 天多次获取结果。

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

路径参数

参数名	类型	说明
id	string	任务唯一标识，UUID 格式。任务提交后可在 30 天通过该 ID 随时获取结果。

返回结构

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

顶层字段

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

建议在接时实现完备的异常处理机制，覆盖状态码异常、空结果、任务未完成等。

tasks[] 字段

字段名	类型	说明
id	string	任务 ID，UUID 格式
status_code	integer	任务状态码，通常范围为 10000-60000
status_message	string	任务状态信息
time	string	当前任务执行耗时，单位秒
cost	float	当前任务成本
result_count	integer	result 数组中的结果数量
path	array	请求路径
data	object	与创建任务时传的参数一致
result	array	预估结果数组

tasks[].data 字段

data 中通常会回显创建任务时提交的参数，例如：

字段名	类型	说明
api	string	接口所属产品模块
function	string	功能名称，当前为 audience_estimation
se	string	搜索引擎/广告平台标识，当前为 bing
id	string	任务 ID
location_coordinate	string	地理位置坐标及半径
age	array / null	年龄定向条件
bid	float	出价
daily_budget	float	日预算
gender	array / null	性别定向条件
industry	array / null	行业定向条件
job_function	array / null	职能定向条件

tasks[].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	float	当前定向条件及出价下的建议日预算
events_lost_to_bid	integer	因出价不足而损失的事件数量
events_lost_to_budget	integer	因预算不足而损失的事件数量
est_reach_audience_size	integer	月度预估触达用户数
est_reach_impressions	integer	月度预估量
currency	string	货币名称，例如 USDollar

请求示例

cURL

id="10081455-0001-0110-0000-c75b21dcca1c"

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

Python

import requests

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

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

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

# 输出返回结果
print(result)

TypeScript

import axios from "axios";

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

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/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);
 });

响应示例

{
 "version": "0.1.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "audience_estimation",
 "se": "bing",
 "id": "09271515-1535-0594-0000-37caebb347d4",
 "location_coordinate": "29.6821525,-82.4098881,100",
 "age": null,
 "bid": 1,
 "daily_budget": 24,
 "gender": null,
 "industry": null,
 "job_function": null
 },
 "result": []
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整次请求的处理状态
• tasks[].status_code 表示单个任务的处理状态
• 建议重点处理以下：
• 顶层请求成功，但任务结果为空
• 任务尚未完成，result 暂无数据
• 任务 ID 不存在或已过 30 天有效期
• 参数格式错误或鉴权失败

完整错误码列表可参考 /v3/appendix/errors。

使用建议

1. 通过对应的 POST 接口提交受众预估任务。
2. 保存返回的任务 id。
3. 轮询或延迟调用本接口获取结果。
4. 当 result 返回有效数据后，提取建议出价、预算、CTR、与点击区间，用于广告投放测算。
5. 若需要批量处理任务，建议结合任务列表或就绪任务接口统一调度。

实用场景

• 评估广告定向覆盖规模：根据地域、年龄、性别、行业、职能等条件预估可触达人群，帮助投放前判断受众池是否足够大。
• 优化出价策略：结合 suggested_bid 与 events_lost_to_bid 判断当前出价是否偏低，从而减少因竞价不足带来的转化损失。
• 规划预算分：通过 suggested_budget、est_spend 与 events_lost_to_budget 评估预算是否合理，为日预算设置提供依据。
• 预测投放效果：利用 est_impressions、est_clicks、est_ctr 提前估算与点击表现，制定广告投放预期。
• 对比不同受众组合：针对多个定向方案分别创建任务并获取结果，对比不同人群的覆盖与成本，筛选更优投放方案。