获取广告表现对比数据
您可以使用本接口获取广告表现与行业基准值的对比数据。
注意
通过本接口返回的所有数据都有30~48小时的延迟。
使用前需知
请确保您要与行业基准值对比的广告在对比的时间窗口期内均已累积了至少1,000次展示。若广告在对比的时间窗口期内已累积的展示次数少于1,000，将返回空结果。若想检查广告在某个时间区间内的展示数，可调用/report/integrated/get/接口创建报表。需传入start_date 和 end_date 字段，并在metrics中包含指标impressions。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径| /v1.2/reports/ad_benchmark/get/|/v1.3/report/ad_benchmark/get/|
|请求参数名称|order_field<br>order_type|sort_field<br>sort_type|
|请求参数类型|advertiser_id: number <br>ad_ids(位于filtering下): number[] <br>adgroup_ids(位于filtering下): number[] <br>campaign_ids(位于filtering下): number[] |advertiser_id: string <br>ad_ids(位于filtering下): string[] <br>adgroup_ids(位于filtering下): string[] <br>campaign_ids(位于filtering下): string[] |
|返回参数类型|ad_id(位于info下): number<br>metric_name(位于in metrics下) : string|ad_id(位于info下) : string<br>metric_name(位于metrics下) : number|
|废弃返回参数|/|metric_value`(位于metrics下) : number|
## 支持指标
```xtable
|指标{30%}| 描述{70%}|
|-|-|
|cost| 成本|
|click|点击量|
|impression|展示量|
|conversion|转化|
|cpa|每次行动成本|
|cpc|每次点击成本|
|cpm|每千次展现成本|
|cpv|每次浏览成本|
|ctr|点击率|
|cvr|转化率|
|pvr|页面浏览率|
|profile_visits_rate|主页访问率|
|video_views| 视频播放次数|
|video_watched_2s|视频播放到2秒的次数|
|video_watched_6s|视频播放到6秒的次数|
|video_views_p25|视频播放到25%的次数|
|video_views_p50| 视频播放到50%的次数|
|video_views_p75|视频播放到75%的次数|
|video_views_p100| 视频播放到100%的次数|
|average_video_play|平均视频播放时长|
请求
地址 https://business-api.tiktok.com/open_api/v1.3/report/ad_benchmark/get/
方法 GET
Header
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_id {必填}|string| 广告主 ID。 |
|compare_time_window|string|对比的时间窗口。 枚举值：`7` (默认), `14`, `30`, `60`。|
|dimensions {必填}|string[]|对比维度。可以传入1-4个维度。枚举值： `LOCATION`（地域）, `AD_CATEGORY`（兴趣分类）, `EXTERNAL_ACTION`（转化事件）, `PLACEMENT`（版位）。|
|metrics_fields|string[]|你想获取的指标。默认返回所有指标。支持的指标可见<b>支持指标</b>表格。|
|filtering {Required}|object| 筛选条件。你只能传入三个条件中的一个条件，且必须传入一个条件。|
#|ad_ids|string[]|你想获取对比数据的广告ID列表|
#|adgroup_ids|string]| 你想获取对比数据的广告组ID列表|
#|campaign_ids|string[]|你想获取对比数据的广告推广系列ID列表|
|sort_field|string| 排序依据的字段。默认根据创建时间(`CREATE_TIME`)排序|
|sort_type|string|排序类型。枚举值: `ASC` (升序，从最早创建的开始), `DES` (降序，从最晚创建的开始)|
|page|number|页号|
|page_size|number| 页面大小|
示例
(code Success-Response http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/report/ad_benchmark/get/?advertiser_id={{advertiser_id}}&dimensions=["LOCATION"]&filtering={{filtering}}&sort_field=AD_ID&sort_type=ASC&page=1&page_size=10&metrics_fields=["cost","impression","click","cpa"]' \
--header 'Content-Type: application/json' \
--header 'Access-Token: {{Access-Token}}'
(/code);
返回
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|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|返回数据。 |
#|compare_date|string|对比的日期。|
#|list|object|结果列表。<br><br><p><span style="color:darkred"><b>注意</b></span>：若广告在对比的时间窗口期（`compare_time_window`）内已累积的展示次数少于1,000，则表现对比数据将为空。|
##|info|object|对比对象信息。|
###|ad_id|string|广告ID。|
###|location|string|2个字母的国家或地区代码。|
###|placement|string|版位。|
###|ad_category|number|二级兴趣分类ID。详细信息，请参考 [获取兴趣分类列表](https://ads.tiktok.com/marketing_api/docs?id=1737174348712961)。若需确定游戏相关兴趣分类ID对应的兴趣分类名称，请查看[兴趣分类](1738865030529025.html)。|
###|external_action|string|广告的外部事件/转化事件。|
##|metrics|object|指标以及相应的值。|
###|metric_name|number| 返回的具体指标，由您在请求中设置的`metrics_fields`决定。<br>指标名后您可以看到一个保留一位小数的数字，取值范围 [0.0,1.0]。该数字代表在您请求中所指定的维度（`dimensions`）下，该广告的该指标表现在所有广告中的排名。例如`"video_watched_6s": 0.6`代表在所指定的维度下，该广告"video_watched_6s"指标的表现超过了约60%的广告。<br>支持的指标可参见上文<b>支持指标</b>小节。|
#|page_info|object|分页信息。|
##|page|number|当前页码。|
##|total_page|number|总页数。|
##|page_size|number|页面大小。默认值: 10。|
##|total_number|number|总结果数。|
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "2021120912121801024524603910501234",
"data": {
"compare_date": "2021-12-05",
"list": [
{
"info": {
"placement": "TIKTOK",
"ad_id": "1234943678835714",
"location": "VN",
"ad_category": "0",
"external_action": "FORM_BUTTON"
},
"metrics": {
"video_watched_6s": 0.6,
"video_views_p25": 0.4,
"click": 0.8,
"video_views_p100": 0.4,
"average_video_play": 0.2,
"video_views_p50": 0.4,
"cpm": 0.1,
"profile_visits_rate": 0.9,
"cost": 0.7,
"impression": 0.8,
"cpa": 0.8,
"video_views_p75": 0.4,
"cpv": 0.0,
"cpc": 0.1,
"cvr": 0.2,
"ctr": 0.4,
"video_watched_2s": 0.7,
"pvr": 0.2,
"conversion": 0.6,
"video_views": 0.8
}
},
{
"info": {
"ad_id": "1234003068951586"
}
}
],
"page_info": {
"page": 1,
"total_page": 1,
"page_size": 10,
"total_number": 2
}
}
}
(/code);