设置 Bing Ads 受众估算任务

POST /v3/keywords_data/bing/audience_estimation/task_post

本接口使用 POST /v3/keywords_data/bing/audience_estimation/task_post 创建 Bing Ads 受众估算任务。

接口根据指定的定位条件，估算广告活动的受众规模，并返回预计受众总量、建议出价、预算和参与度等指标。

本接口采用标准任务模式：提交任务后，系统异步采集数据。任务完成后，可通过任务 ID 获取结果。执行时间取决于系统负载。

如果业务需要实时返回结果，可使用实时查询接口。实时模式会在同一个请求中完成任务提交和结果返回，无需分别调用 POST 和 GET 接口。

请求地址

text

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

计费说明

提交任务时计费，无论后续是否通过任务 ID 获取结果，均不会重复收取任务设置费用。

参考价约 ¥0.36 / 任务（示例响应中的 0.05 USD 按参考汇率折算供价格说明）。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

请求体使用 UTF-8 编码的 JSON 格式。
请求体是 JSON 数组，每个数组代表一个任务。
单次请求最多 100 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
如果单次请求 100 个任务，出部分将返回错误码 40006。
可通过任务返回的唯一 id 获取任务结果。
提交任务时也可以指定 postback_url 或 pingback_url，任务完成后由本平台向指定地址推送结果。
如果接收服务器在 10 秒未响应，推送连接将因时中止，任务会转 tasks_ready 列表。错误码和错误信息取决于接收服务器。

请求参数

每个任务对象支持以下字段：

字段	类型	说明
`location_name`	string	搜索引擎位置的完整名称。如果未指定 `location_code` 或 `location_coordinate`，则填。使用此字段后，无需再指定另外两个位置字段。可通过 `/v3/keywords_data/bing/locations` 获取可用位置名称。示例：`London,England,United Kingdom`
`location_code`	integer	搜索引擎位置代码。如果未指定 `location_name` 或 `location_coordinate`，则填。使用此字段后，无需再指定另外两个位置字段。可通过 `/v3/keywords_data/bing/locations` 获取可用位置代码。示例：`2840`
`location_coordinate`	string	位置的 GPS 坐标，格式为 `"纬度,经度,半径（）"`。数据将指定坐标所属国家提供。示例：`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	目标出价，单位为。最大值：`1000`。使用时请根据账户币种和投放换算。
`daily_budget`	float	广告活动每日预算，单位为。最大值：`10000`。使用时请根据账户币种和投放换算。
`gender`	array	目标性别。可选值：`male`、`female`、`unknown`
`industry`	array	LinkedIn 资料定位中的行业 ID。可通过 `/v3/keywords_data/bing/audience_estimation/industries` 获取可用行业名称及对应 ID。示例：`806301758`
`job_function`	array	LinkedIn 资料定位中的职能 ID。可通过 `/v3/keywords_data/bing/audience_estimation/job_functions` 获取可用职能名称及对应 ID。示例：`806300451`
`postback_url`	string	可选。任务完成后接收结果推送的 URL。
`pingback_url`	string	可选。任务完成后接收结果通知的 URL。

位置参数互斥

以下三个字段至少提供一个，且不建议同时提供：

location_name
location_code
location_coordinate

请求示例

cURL

bash

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": 10,
      "daily_budget": 24,
      "gender": ["male", "female"],
      "industry": [806301758],
      "job_function": [806300451]
    }
  ]'

PHP

php

<?php

$apiUrl = 'https://api.seermartech.cn';
$apiKey = 'smt_live_YOUR_KEY';

$postData = [
    [
        'location_code' => 2840,
        'bid' => 10,
        'daily_budget' => 24
    ]
];

$ch = curl_init($apiUrl . '/v3/keywords_data/bing/audience_estimation/task_post');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($postData, JSON_UNESCAPED_UNICODE)
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new Exception(curl_error($ch));
}

curl_close($ch);

$result = json_decode($response, true);

if ($result['status_code'] === 20000) {
    print_r($result);
} else {
    echo '错误码：' . $result['status_code'] . PHP_EOL;
    echo '错误信息：' . $result['status_message'] . PHP_EOL;
}

TypeScript

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: 10,
        daily_budget: 24,
        gender: ["male", "female"],
        industry: [806301758],
        job_function: [806300451],
      },
    ]),
  }
);

const result = await response.json();

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(
    `错误码：${result.status_code}，错误信息：${result.status_message}`
  );
}

Python

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",
}

post_data = [
    {
        "location_code": 2840,
        "bid": 10,
        "daily_budget": 24,
        "gender": ["male", "female"],
        "industry": [806301758],
        "job_function": [806300451],
    }
]

response = requests.post(url, headers=headers, json=post_data)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

响应结构

接口返回 JSON 对象 tasks 数组已创建任务的信息。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	顶层状态码。`20000` 表示请求成功。完整错误码请参考错误码文档。
`status_message`	string	顶层状态说明
`time`	string	请求执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量
`tasks`	array	任务信息数组

`tasks` 数组字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	当前任务状态码，通常位于 `10000` 至 `60000` 范围
`status_message`	string	当前任务状态说明
`time`	string	任务执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量
`path`	array	请求 URL 路径
`data`	object	创建任务时提交的参数
`result`	array / null	任务结果数组。创建任务成功后，此字段通常为 `null`，需要在任务完成后获取结果。

响应示例

json

{
  "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": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0187 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",
          "female"
        ],
        "industry": [
          806301758
        ],
        "job_function": [
          806300451
        ]
      },
      "result": null
    }
  ]
}

状态码与错误处理

顶层 status_code 为 20000：请求已成功处理。
单个任务的 status_code 用于表示该任务的创建状态或错误状态。
单次请求 100 个任务时，出限制的任务将返回 40006。
建议客户端同时检查：
- HTTP 状态码；
- 顶层 status_code；
- 每个任务的 status_code；
- tasks_error 是否大于 0。
完整状态码和错误信息请参考错误码文档。

实用场景

评估广告受众规模：根据地区、年龄和性别预估目标受众数量，为广告投放范围和预算规划提供依据。
比较不同定位组合：批量提交多个行业、职能或人口属性组合，筛选潜在受众更大的定向方案。
制定广告预算：结合 bid 和 daily_budget 估算不同出价与日预算下的投放潜力，制定媒体采购计划。
构建 LinkedIn 职业人群画像：使用行业和职能 ID 评估企业决策、专业人士等职业人群的可触达规模。
批量生成投放建议：通过一次提交多个任务，为不同国家、地区或人群建立受众规模对比报表，支持 SEO 与付费搜索协同决策。

设置 Bing Ads 受众估算任务 ​

请求地址 ​

计费说明 ​

请求说明 ​

请求参数 ​

位置参数互斥 ​

请求示例 ​

cURL ​

PHP ​

TypeScript ​

Python ​

响应结构 ​

顶层响应字段 ​

tasks 数组字段 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​