获取广告报告
使用 POST /v2/research/adlib/ad/report/ 获取广告投放报告。
HTTP URL | https://open.tiktokapis.com/v2/research/adlib/ad/report/ |
HTTP 请求方法 | POST |
权限范围 | research.adlib.basic |
请求
请求头
Key | 类型 | 描述 | 示例 | 是否必填 |
Authorization | 字符串 (String) | TikTok 用户授权的访问令牌，通过 /v2/oauth/token/ 获取。 | Bearer clt.example12345Example12345Example | 是 |
Content-Type | 字符串 (String) | 资源的原始媒体类型。 | application/json | 是 |
查询参数
Key | 类型 | 描述 | 示例 | 是否必填 |
fields | 字符串 (String) | 请求的字段：
| count_time_series_by_country | 是 |
请求体
Key | 类型 | 描述 | 示例 | 是否必填 |
filters | RequestFilters | 查询中使用的筛选条件。 | 请参见下方的请求示例。 | 是 |
数据结构
RequestFilters
Key | 类型 | 描述 | 示例 | 是否必填 |
ad_published_date_range | DateRange | 广告发布的时间范围。 “min”值所代表的日期必须晚于 2022 年 10 月 1 日。 | { "min": "20230102", "max": "20230109" } | 是 |
country_code | 字符串 (String) | 广告/广告组制作地国家/地区。默认值为 ALL。 | FR | 否 |
advertiser_business_ids | list<i64> | 广告/广告组所属广告主的企业 ID。 | [21836478203048,3484763562784] | 否 |
DateRange
Key | 类型 | 描述 | 示例 | 是否必填 |
min | 字符串 (String) | 查询范围的起始日期。 “min”值所代表的日期必须晚于 2022 年 10 月 1 日。 | 20230102 | 是 |
max | 字符串 (String) | 查询范围的结束日期。 | 20230109 | 是 |
请求示例
curl -L -X POST 'https://open.tiktokapis.com/v2/research/adlib/ad/report/?fields=count_time_series_by_country' \
-H 'Authorization: Bearer clt.example12345Example12345Example' \
-H 'Content-Type: application/json' \
--data-raw '{
"filters":{
"ad_published_date_range": {
"min": "20230102",
"max": "20230109"
},
"country_code":"IT"
}
}'响应
Key | 类型 | 示例 |
data | ReportData | 请参见以下响应示例。 |
error | ErrorStructV2 | 请参见以下响应示例。 |
响应示例
{
"data": {
"count_time_series_by_country": {
"IT": [{"date": "20210109", "count": 45}, {"date": "20210108", "count": 24}],
"ES": [{"date": "20210109", "count": 48}, {"date": "20210108", "count": 22}],
...
}
},
"error": {
"code": "ok",
"http_status_code": 200,
"log_id": "202207280326050102231031430C7E754E",
"message": ""
}
}数据结构
ReportData
Key | 类型 | 描述 | 示例 |
count_time_series_by_country | map<string,list<DateCount>> | 根据日期统计的每个国家/地区的广告数量。 |
DateCount
Key | 类型 | 描述 | 示例 |
date | 字符串 (String) | 广告发布日期，格式为 YYYYMMDD。 | 20230101 |
count | i64 | 当天发布的广告总数。 | 500032 |
ErrorStructV2
Key | 类型 | 描述 | 示例 |
code | 字符串 (String) | 字符串格式的错误类别代码。 | ok |
message | 字符串 (String) | 详细的错误描述。 | "" |
log_id | 字符串 (String) | 与对应请求关联的唯一日志 ID，用于错误处理。 | 202207280326050102231031430C7E754E |
http_status_code | i32 | HTTP 状态码。 | 200 |