根据任务 ID 获取应广告受众预估结果

本接口使用 GET 方法，通过以下路径获取应广告受众预估任务的结果：

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

接口根据任务创建时设置的定向条件，返回广告活动的预计受众规模、展示量、点击量、花费、建议出价、建议预算及参与度指标。

计费说明

提交受众预估任务时会产生费用；任务结果可在任务创建后的 30 天重复获取，获取结果本身不额外计费。

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

请求说明

请求参数

该接口通过 URL 路径传任务 ID，无请求体。

参数	类型	说明
`id`	string	任务唯一标识符，UUID 格式。任务创建后 30 天可随时使用该 ID 获取结果。

请求头

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

响应说明

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

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	顶层状态码。完整状态码列表请参考错误码文档。
`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	请求路径信息。
`data`	object	创建任务时提交的参数。
`result`	array	受众预估结果数组。

`result` 数组中的字段

字段	类型	说明
`est_impressions`	object	每月预计展示量范围。
`est_audience_size`	object	每月预计可触达用户数范围。
`est_clicks`	object	每月预计点击量范围。
`est_spend`	object	每月预计花费范围。
`est_cost_per_event`	object	每次事件预计成本范围。
`est_ctr`	object	预计点击率范围。
`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`	integer	货币名称字段。示例值为 `USDollar`。

范围对象字段

以下字段均为范围对象：

字段	类型	说明
`high`	integer / float	范围上限。
`low`	integer / float	范围下限。

：

est_impressions、est_audience_size、est_clicks、est_spend 的 high 和 low 为整数。
est_cost_per_event、est_ctr 的 high 和 low 为浮点数。

cURL 示例

bash

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

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

TypeScript 示例

typescript

import axios from "axios";

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

axios
  .get(
    `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.response?.data || error.message);
  });

Python 示例

python

import requests

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

url = (
    "https://api.seermartech.cn/v3/keywords_data/bing/"
    f"audience_estimation/task_get/{task_id}"
)

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

response = requests.get(url, headers=headers, timeout=30)
response.raise_for_status()

data = response.json()

if data.get("status_code") != 20000:
    print(
        f"请求失败：{data.get('status_code')} "
        f"{data.get('status_message')}"
    )
else:
    for task in data.get("tasks", []):
        if task.get("status_code", 0) >= 40000:
            print(
                f"任务失败：{task.get('status_code')} "
                f"{task.get('status_message')}"
            )
        else:
            print("受众预估结果：", task.get("result"))

响应示例

json

{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "09271515-1535-0594-0000-37caebb347d4",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "audience_estimation",
        "task_get",
        "09271515-1535-0594-0000-37caebb347d4"
      ],
      "data": {
        "api": "keywords_data",
        "function": "audience_estimation",
        "se": "bing",
        "id": "09271515-1535-0594-0000-37caebb347d4",
        "location_coordinate": "29.6821525,-82.4098881,100",
        "age": [],
        "bid": 1,
        "daily_budget": 24,
        "gender": [],
        "industry": [],
        "job_function": []
      },
      "result": [
        {
          "est_impressions": {
            "high": 100000,
            "low": 50000
          },
          "est_audience_size": {
            "high": 80000,
            "low": 30000
          },
          "est_clicks": {
            "high": 5000,
            "low": 2000
          },
          "est_spend": {
            "high": 2400,
            "low": 800
          },
          "est_cost_per_event": {
            "high": 2.5,
            "low": 1.2
          },
          "est_ctr": {
            "high": 0.06,
            "low": 0.03
          },
          "suggested_bid": 1.1,
          "suggested_budget": 30,
          "events_lost_to_bid": 120,
          "events_lost_to_budget": 80,
          "est_reach_audience_size": 55000,
          "est_reach_impressions": 72000,
          "currency": "USDollar"
        }
      ]
    }
  ]
}

错误处理

建议同时检查顶层和任务级状态码：

顶层 status_code 用于判断整个请求是否成功。
tasks[].status_code 用于判断任务是否成功。
当任务状态码表示错误，或 result 为空时，应读取对应的 status_message 并执行重试、告警或人工排查。
任务结果在任务创建后的 30 天可获取，有效期后应重新创建任务。

实用场景

评估广告受众规模：根据年龄、性别、行业、职位等定向条件估算潜在受众，判断广告计划是否备足够市场覆盖。
制定竞价和预算策略：结合 suggested_bid 与 suggested_budget 设置初始出价和每日预算，降低广告投放的试错成本。
比较不同定向组合：分别创建多组定向任务并对比预计展示量、点击量和点击率，筛选更投放效率的受众组合。
识别预算或出价损失：通过 events_lost_to_bid 和 events_lost_to_budget 判断转化事件损失来源，优化广告预算分和出价水平。
构建投放预测报表：汇总预计触达人数、展示量、点击量和花费范围，为 SEO、SEM 及增长团队提供投放计划评估依据。

根据任务 ID 获取应广告受众预估结果 ​

计费说明 ​

请求说明 ​

请求参数 ​

请求头 ​

响应说明 ​

顶层字段 ​

tasks 数组中的任务字段 ​

result 数组中的字段 ​

范围对象字段 ​

cURL 示例 ​

TypeScript 示例 ​

Python 示例 ​

响应示例 ​

错误处理 ​

实用场景 ​