获取覆盖和频次广告库存预估
您可以使用本接口获取覆盖和频次广告的库存预估。参考这里了解更多库存预估的细节，及该接口返回结果与TikTok广告管理平台预测结果的匹配关系。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{23%}|v1.2{37%}|v1.3{40%}|
|---|---|---|
|接口路径|/v1.2/adgroup/rf/inventory/estimate/|/v1.3/rf/inventory/estimate/|
|请求参数名称|age<br>operation_system<br>connection_type<br>device_price<br>brand_safety|age_groups<br>operating_systems<br>network_types<br>device_price_ranges<br>brand_safety_type|
|请求参数类型|advertiser_id: number |advertiser_id: string|
|请求参数名称和名称|audience: number[]<br>excluded_audience: number[] <br>location: number[]<br>device_models: number[] <br>carriers_v2: number[] <br>interest_category_v2: number[] |audience_ids: string[]<br>excluded_audience_ids: string[]<br>location_ids: string[]<br>device_model_ids: string[]<br>carrier_ids: string[]<br>interest_category_ids: string[]|
|废弃请求参数| /|reach_percentage|
|新增请求参数|/|rf_purchased_type: string<br>budget: float<br>purchased_impression: number<br>purchased_reach: number<br>rf_campaign_type: string<br>contextual_tag_ids: string[]|
|废弃返回参数|/|estimate_key<br>max_reach|
|新增返回参数| / |max_reach` |
## 请求
**地址** https://business-api.tiktok.com/open_api/v1.3/rf/inventory/estimate/
**方法** GET
**Header**
``` xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
参数
|字段|类型|描述|
|---|---|---|
|advertiser_id {必填}|string| 广告主ID。 |
|audience_info{必填} |object| 受众定向规则。 |
#|audience_ids | string[]|想要定向的受众ID列表。若要将受众在覆盖和频次广告中定向或排除，需要在创建或更新受众时，将`audience_sub_type`设置为`REACH_FREQUENCY`。 |
#|excluded_audience_ids|string[]|要排除的受众ID列表。若要将受众在覆盖和频次广告中定向或排除，需要在创建或更新受众时，将`audience_sub_type`设置为`REACH_FREQUENCY`。|
#|age_groups |string[]| 受众年龄区间。若定向地区包括以色列和巴西，则此字段不可设置为`AGE_13_17`。枚举值可见[枚举值-受众年龄区间](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 |
#|gender |string| 受众性别。 枚举值详见[枚举值 - 性别](https://ads.tiktok.com/marketing_api/docs?id=1006411737174886619138)。|
#|languages |string[]| 受众语言。枚举值详见[枚举值-受众语言](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 |
#|location_ids {必填} |string[]| 定向地域ID。所定向地域可为国家或地区层级，省、指定市场区域或都会区层级，或城市层级地域。<br>只支持定向到单个国家或地区。如果传入了多个ID，则这些ID必须属于同一国家或地区。<br>支持投放覆盖和频次广告的国家和地区请参见[覆盖和频次广告](https://ads.tiktok.com/marketing_api/docs?id=1738235311704065)开头部分。地域ID列表可参见[附录-地区定向](https://ads.tiktok.com/marketing_api/docs?id=1739311040498689)。|
#|operating_systems |string[]| 操作系统。枚举值详见[枚举值-受众操作系统](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 |
#|network_types |string[]|网络类型。不传即不限制网络类型。枚举值详见[枚举值-网络类型](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
#| device_model_ids| string[]| 想要定向的设备机型ID列表。目前只支持定向到品牌层级。传入本字段时，设备价格字段`device_price_ranges`不可同时传入。所有设备机型ID的枚举值可通过 [设备机型](https://ads.tiktok.com/marketing_api/docs?id=1737172880570369)接口获取。<br><p><span style="color:darkred"><b>注意</b></span>: 创建广告时需确保对应设备处于活跃状态（ [/tool/device_model/](https://ads.tiktok.com/marketing_api/docs?id=1737172880570369) 接口返回中`is_active` 为 `True`）。|
#|device_price_ranges |number[]|设备价格区间（10000代表1000+）。该数字必须是50的倍数。<br><b><span style="color: darkred">重要提示</span></b>: 最终的实际上限将在您设定的上限基础上增加50，您可以在TikTok广告管理平台的广告组设置中看到实际上限。例如，如果您设置的价格区间是[0, 250]，实际区间则为[0, 300]。|
#|carrier_ids |string[]| 运营商ID列表。您可使用 [/tool/carrier/](https://ads.tiktok.com/marketing_api/docs?id=1737168013095938) 接口获取此字段的枚举值。|
#|interest_category_ids |string[]| 兴趣分类。不传即不限制兴趣分类，若想定向所有受众，请不要传入此字段。您可以使用[/tool/target_recommend_tags/](https://ads.tiktok.com/marketing_api/docs?id=1736275204260866)接口获取推荐兴趣分类，推荐结果将基于您的定向地区及所在行业。您还可以使用[/tool/interest_category/](https://ads.tiktok.com/marketing_api/docs?id=1737174348712961) 接口获取兴趣分类枚举值。|
#|brand_safety_type|string|覆盖和频次广告的品牌安全类型。默认值：`NO_BRAND_SAFETY`。枚举值： <ul><li>`NO_BRAND_SAFETY`：不使用任何品牌安全解决方案，即使用<strong>全部库存</strong>。您的广告可能会在某些包含成人主题的内容周围展示。</li><li>`EXPANDED_INVENTORY`：使用TikTok的品牌安全解决方案，即使用<b>扩展库存</b>。您的广告将不会出现在不当内容或包含成人主题的内容后面。在下个API版本中`EXPANDED_INVENTORY`将替代`NO_BRAND_SAFETY`，并成为默认的品牌安全选项。</li><li>`STANDARD_INVENTORY`：使用TikTok的品牌安全解决方案中的<strong>标准库存</strong>。您的广告将展示在适合大多数品牌的内容周围。 </li><li>`LIMITED_INVENTORY`：使用TikTok的品牌安全解决方案中的<strong>有限库存</strong>。您的广告将展示在不包含成人主题的内容周围。</li><li>`THIRD_PARTY`：使用第三方品牌安全解决方案。</li></ul>您可以使用[/tool/region/](https://ads.tiktok.com/marketing_api/docs?id=1737189539571713)接口查询品牌安全设置对应的广告可投放国家或地区。<br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>出价前第三方品牌安全解决方案目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。</li></ul>|
#|contextual_tag_ids |string[]|内容相关定向标签ID列表。您可使用 [/tool/contextual_tag/get/](https://ads.tiktok.com/marketing_api/docs?id=1747747118654465)获取可用的内容相关定向标签。<br><p><span style="color:darkred"><b>注意</b></span>：<ul><li> 本字段目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。</li><li>仅支持推广系列的推广目标为`RF_REACH` 。</li><li>不支持同时将`brand_safety_type`设置为`THIRD_PARTY`。</li><li>不支持同时将`feed_type`设置为 `TOP_FEED`。</li><li>若您使用[/campaign/create/](https://ads.tiktok.com/marketing_api/docs?id=1739318962329602)创建推广系列时，将`rf_campaign_type` 设置为`PULSE`，则需在本字段（`contextual_tag_ids`）传入 `PREMIUM`类型的内容相关定向标签，创建的广告组的CPM（`cpm`）将是固定的。</li></ul>|
|schedule_start_time {必填}|string| 排期开始时间（UTC+0）。格式： "YYYY-MM-DD HH:MM:SS"，"HH:MM:SS"的值需由投放地时区某天的00:00:00时间转换成UTC+0的时间。例如，若想在UTC-5 时区地区的 `2020-10-24 00:00:00`时间开始投放，需在此字段传入`2020-10-24 05:00:00`（UTC+0时间）。<br><p><span style="color:darkred"><b>注意</b></span>：若您指定的定向地域 (`location_ids`)遵守夏令时，请忽略夏令时的影响，传入标准时间。<br>例如，若您想在荷兰当地时间`2022-04-02 00:00:00` （夏令时已开始，UTC+2时区）开始投放，需将时区视作标准时区（UTC+1），并将本字段设置为`2022-04-02 23:00:00`。|
|schedule_end_time {必填}|string| 排期结束时间（UTC+0）。格式： "YYYY-MM-DD HH:MM:SS"。"HH:MM:SS"的值需由投放地时区某天的23:59:59时间转换成UTC+0的时间。例如，若想在UTC-5 时区地区的 `2020-11-10 23:59:59`时间结束投放，需在此字段传入`2020-11-11 04:59:59`（UTC+0时间）。`schedule_end_time` 与 `schedule_start_time` 的时间间隔不能超过30天。<br><p><span style="color:darkred"><b>注意</b></span>：若您指定的定向地域 (`location_ids`)遵守夏令时，请忽略夏令时的影响，传入标准时间。<br>例如，若您想在荷兰当地时间`2022-04-02 23:59:59`（夏令时已开始，为UTC+2时区）结束投放，需将时区视作标准时区（UTC+1），并将本字段设置为`2022-04-02 22:59:59`。 |
|frequency {必填}|number| 频次。本字段与 `frequency_schedule` 共同定义用户看到广告的频次上限（仅适用于覆盖和频次广告）。<br>例如，`frequency` = 2 且`frequency_schedule` = 3， 表示每 3 天至多 2 次展示。<br>需满足以下条件： <ul><li>1 ≤ `frequency` ≤ `frequency_schedule`</li><li>1 ≤ `frequency_schedule` ≤ min(`schedule_end_time` - `schedule_start_time`, 30)</li><li>由`frequency` 和 `frequency_schedule` 定义的频次上限不可超过每天 4 次展示。</li></ul> |
|frequency_schedule {必填}|number| 频次天数。与 `frequency` 共同定义用户看到广告的频次上限（仅适用于覆盖和频次广告）。请查看`frequency`字段的描述。 |
|objective_type {必填}| string | 推广目标。枚举值：`RF_REACH`。|
|cpv_video_duration| string | 目标视频播放时长。<br>枚举值：`SIX_SECONDS`(视频播放6秒)，`TWO_SECONDS`(视频播放2秒)。|
|feed_type |string| 信息流类型。枚举值: `STANDARD_FEED`, `TOP_FEED`。`STANDARD_FEED`指库存高，且CPM价格正常。`TOP_FEED` 指库存受限，且CPM价格较高。|
| rf_purchased_type | string | 购买类型。枚举值：<ul><li>`FIXED_SHOW`: 按固定展示量购买。</li><li>`FIXED_REACH`:按固定覆盖人数购买。 </li><li>`FIXED_BUDGET`: 按固定预算购买。</li></ul> |
| budget {+条件必填}| float | 预算金额。当`rf_purchased_type` 为 `FIXED_BUDGET`时必填。基于您设置的预算金额，其他字段会返回预估值。 |
| purchased_impression {+条件必填}| number | 想购买的展示量，<b>以1000为单位</b>。当 `rf_purchased_type`为 `FIXED_SHOW`时必填。基于您设置的展示量，其他字段会返回预估值。 |
| purchased_reach {+条件必填} | number | 想购买的覆盖人数，<b>以1000为单位</b>。当 `rf_purchased_type` 为`FIXED_REACH`时必填。 基于您设置的覆盖人数，其他字段会返回预估值。 |
|rf_campaign_type |string|仅当推广目标（`objective_type`）设置为`RF_REACH`时，可用此字段将推广系列设置为TikTok Pulse推广系列，从而获取`PREMIUM`标签。<br><br>枚举值： `STANDARD` （普通覆盖和频次推广系列）， `PULSE`（TikTok Pulse推广系列）。 <br><br>若指定为`PULSE`，则仅返回一个国家或地区ID(`location_id`)。<br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>推广目标非`RF_REACH`时，本字段无需传入。</li><li>使用[/adgroup/rf/create/](https://ads.tiktok.com/marketing_api/docs?id=1738235338194945) 创建TikTok Pulse广告组时，请求中需将本接口返回的`location_id`值传给`location_ids`。</li></ul>|
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/rf/inventory/estimate/?advertiser_id={{advertiser_id}}&objective_type=RF_REACH&audience_info={%22location_ids%22%3A[%22{{location_id}}%22]}&schedule_start_time={{schedule_start_time}}&schedule_end_time={{schedule_end_time}}&frequency={{frequency}}&frequency_schedule={{frequency_schedule}}&rf_purchased_type=FIXED_BUDGET&budget={{budget}}' \
--header 'Access-Token: {{Access-Token}}'
}'
(/code)
返回
|字段{40%}|类型{15%}|描述{45%}|
|---|---|---|
|code |number|返回码。完整返回码列表及描述，可查看[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|message |string|返回信息。更多信息可查看[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|request_id |string|请求的日志ID，唯一标识一个请求。 |
|data |object|返回数据。 |
#|default_result |object| 库存预估结果。<br>若您在请求中为`purchased_impression`, `budget`或 `purchased_reach`设置了固定值，则会返回预估库存的对应预估值。例如，若您在请求中为`budget`设置了固定值，则`base_info`对象会返回能够满足您固定预算要求的`impression`, `cpm`, `reach` 以及 `average_frequency`对应值。 |
##|base_info |object| 基本信息。 |
###|budget |float| 总预算。 |
###|cpm |float| 千次展示成本。公式：`cpm` = `budget` / `impression`。 |
###|impression |number| 总展示量，<b>以 1,000 为单位</b>。<br>例如，本字段值为 110 代表总展示量为 110,000。 |
###|reach |number| 总覆盖人数，<b>以 1,000 为单位</b>。<br>例如，本字段值为 110 代表总覆盖人数为 110,000。 |
###| max_reach | number | 可预订的全部覆盖人数，<b>以 1,000 为单位</b>。此数据基于所指定的信息流类型、定向设置和推广系列排期。<br><br>例如，本字段值为 200 代表可用库存中人数为 200,000。|
###|average_frequency |float| 公式：人均展示频次 （`average_frequency`）= 总展示量（`impression`）/总覆盖人数（`reach`）。 |
##|daily_cost |object| 每日花费。 |
###|cost |float| 当日花费。|
###|date |string| 日期。<br>格式：`"YYYY-MM-DD"`。<br>示例：`"2024-01-01"`。 |
##|frequency_per_person |object[]| 人均展示频次分布。<br><p><span style="color:darkred"><b>注意</b></span>：由 `frequency` 和 `frequency_schedule` 定义的频次上限超过每天 4 次展示时，`frequency_per_person` 的值将不再变动。 |
###|frequency |number| 人均展示频次。 |
###|percentage |float| `frequency` 对应的用户人数占比。<br>例如，若`frequency` 为 `1`， `percentage` 为`0.42304230423042305`，则触达次数为 1 的用户占比为约 42.3%。 |
#|results |object[]| 不同预算对应的预估库存结果。每条结果中会返回预算对应的预估展示量、千次展示成本、覆盖人数、频次、每日花费和人均展示频次分布。<br>本对象的数据结构与`default_result` 相同。 |
##|base_info |object| 基本信息。 |
###|budget |float| 总预算。 |
###|cpm |float| 千次展示成本。公式：`cpm` = `budget` / `impression`。 |
###|impression |number| 总展示量。<br>例如，本字段值为 110 代表总展示量为 110,000。 |
###|reach |number| 总覆盖人数。<br>例如，本字段值为 110 代表总覆盖人数为 110,000。 |
###|average_frequency |float| 公式：人均展示频次 （`average_frequency`）= 总展示量（`impression`）/总覆盖人数（`reach`）。 |
##|daily_cost |object| 每日花费。 |
###|cost |float| 当日花费。|
###|date |string| 日期。 |
##|frequency_per_person |object[]| 人均展示频次分布。<br><p><span style="color:darkred"><b>注意</b></span>：由 `frequency` 和 `frequency_schedule` 定义的频次上限超过每天 4 次展示时，`frequency_per_person` 的值将不再变动。 |
###|frequency |number| 人均展示频次。 |
###|percentage |float|`frequency` 对应的用户人数占比。<br>例如，若`frequency` 为 `1`， `percentage` 为`0.42304230423042305`，则触达次数为 1 的用户占比为约 42.3%。 |
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"message": "OK",
"code": 0,
"data": {
"default_result": {
"daily_cost": [
{
"date": "2020-08-07",
"cost": 3587.5169107559
},
{
"date": "2020-08-08",
"cost": 3565.1767601342
},
{
"date": "2020-08-09",
"cost": 3512.4961871912
},
{
"date": "2020-08-10",
"cost": 3537.1785786238
}
],
"frequency_per_person": [
{
"percentage": 0.28,
"frequency": 1
},
{
"percentage": 0.72,
"frequency": 2
}
],
"base_info": {
"impression": 5157,
"average_frequency": 1.72,
"reach": 2991,
"max_reach": 17291,
"cpm": 2.75,
"budget": 14202.37
}
},
"results": [
{
"daily_cost": [
{
"date": "2020-08-07",
"cost": 163.09
},
{
"date": "2020-08-08",
"cost": 163.27
},
{
"date": "2020-08-09",
"cost": 168.63
},
{
"date": "2020-08-10",
"cost": 164.8
}
],
"frequency_per_person": [
{
"percentage": 0.2480487252,
"frequency": 1
},
{
"percentage": 0.7519512748,
"frequency": 2
}
],
"base_info": {
"impression": 418,
"average_frequency": 1.75,
"reach": 239,
"cpm": 1.58,
"budget": 659.8
}
}
]
}
(/code);