设置 Bing Audience Estimation 任务

概述

该接口用于根据指定的广告定向条件，估算广告活动可触达的人群规模。返回预估受众量，以及与投放的建议出价、预算和互动指标等估算数据。

这是标准异步模式接口：创建任务，再在任务完成后获取结果。如果你不要求实时返回数据，这种方式更适合批量处理，执行时间取决于系统负载。

请求地址：

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

如果你的业务需要实时返回结果，应改用对应的 实时（Live）接口；Live 模式无需分开调用 POST 和结果查询接口。

计费说明

该接口在创建任务时扣费。

参考价需以平台价格换算，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

• 请求方法：POST
• Content-Type：application/json
• 编码：UTF-8
• 请求体格式：JSON 数组 [{ ... }]

调用限制

• 每分钟最多可发送 2000 次 API 调用
• 每次 POST 请求最多 100 个任务
• 若单次请求中任务数 100，出部分会返回错误 40006

异步任务机制

创建任务后，你可以通过返回的唯一任务 ID 获取结果。

如果在创建任务时指定了 postback_url 或 pingback_url，本平台也可以在结果生成后主动回调你的服务端。

注意事项：

• 如果你的服务器在 10 秒未响应，连接会因时被中止
• 此类任务会被转移到对应的 tasks_ready 列表中后续拉取
• 实错误码和错误信息取决于你的服务器

请求参数

以下为设置任务时可用的字段。

字段名	类型	说明
location_name	string	搜索引擎地域的完整名称。若未传 location_code 或 location_coordinate，则该字段填。使用该字段时无需再传 location_code 或 location_coordinate。可通过 /v3/keywords_data/bing/locations 获取可用地域列表。示例：London,England,United Kingdom
location_code	integer	搜索引擎地域编码。若未传 location_name 或 location_coordinate，则该字段填。使用该字段时无需再传 location_name 或 location_coordinate。可通过 /v3/keywords_data/bing/locations 获取可用地域编码。示例：2840
location_coordinate	string	地理坐标定位。若未传 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	任务状态信息，完整列表见 /v3/appendix/errors
time	string	任务执行耗时，单位秒
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	与提交时 POST 请求中的任务参数一致
result	array	结果数组。对于 task_post 接口，该值为 null，结果需后续查询

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_code": 2840,
 "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/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "location_code": 2840,
 "bid": 10
 }
]

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

TypeScript

const response = await fetch("https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/task_post", {
 method: "POST",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 body: JSON.stringify([
 {
 location_code: 2840,
 bid: 1,
 daily_budget: 24,
 gender: ["male"],
 industry: [806301758],
 job_function: [806300451]
 }
 ])
});

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

响应示例

{
 "version": "0.1.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1243 sec.",
 "cost": 0.05,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "f1c4f2d4-9f44-4d1d-8fd7-2e4f56b7a001",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0211 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "bing",
 "audience_estimation",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "audience_estimation",
 "se": "bing",
 "location_coordinate": "29.6821525,-82.4098881,100",
 "age": ["twenty_five_to_thirty_four"],
 "bid": 1,
 "daily_budget": 24,
 "gender": ["male"],
 "industry": [806301758],
 "job_function": [806300451]
 },
 "result": null
 }
 ]
}

状态码与错误处理

建议在接时同时处理以下两层状态：

1. 顶层状态：检查 status_code 和 status_message
2. 任务级状态：逐个检查 tasks[].status_code 和 tasks[].status_message

常见处理建议：

• 顶层 status_code = 20000：请求成功被受理
• 任务级 status_code = 20100：任务创建成功
• 若单次请求任务数 100：出部分返回 40006
• 错误码请参考 /v3/appendix/errors

建议你的系统备完善的异常处理机制：

• 参数校验失败
• 任务提交成功但结果未就绪
• 回调时或回调失败
• 单任务失败但整批请求部分成功

使用建议

• 传一个地域字段：location_name、location_code、location_coordinate 三选一
• 批量提交时，将每次请求控制在 100 个任务
• 若需要自动接收结果， postback_url 或 pingback_url
• 若使用 LinkedIn 定向维度，建议调用行业和职能列表接口，缓存可用 ID 后再创建任务

实用场景

• 评估广告定向规模：按地域、年龄、性别、行业、职能组合预估可触达人群，帮助投放前判断定向是否过窄或过宽。
• 优化出价与预算：结合 bid 和 daily_budget 设置测试不同投放方案，制定更合理的广告预算策略。
• 筛选高价值 B2B 人群：通过 industry 与 job_function 定向特定行业和岗位，提升企业服务、SaaS、招聘类广告投放精准度。
• 比较不同地区市场潜力：对多个 location_code 分别创建任务，横向比较不同地区的受众体量，为区域扩张或本地化投放提供依据。
• 构建投放前预估流程：在广告创建前调用本接口进行受众测算，把控流量规模与预算可行性，减少无效投放测试成本。