查询商业内容
使用 POST /v2/research/adlib/commercial_content/query/ 查询商业内容
HTTP URL | https://open.tiktokapis.com/v2/research/adlib/commercial_content/query/ |
HTTP 请求方法 | POST |
权限范围 | research.adlib.basic |
请求
请求头
Key | 类型 | 描述 | 示例 | 是否必填 |
Authorization | 字符串 (String) | 通过 /v2/oauth/token/ 获取的客户端访问令牌。 | Bearer clt.example12345Example12345Example | 是 |
Content-Type | 字符串 (String) | 资源的原始媒体类型。 | application/json | 是 |
查询参数
Key | 类型 | 描述 | 示例 | 是否必填 |
fields | 字符串 (String) | 请求的字段。
| id,create_timestamp,brand_names,creator,videos | 是 |
请求体
Key | 类型 | 描述 | 示例 | 是否必填 |
filters | RequestFilters | 查询中使用的筛选条件。 | 请参见下方的请求示例。 | 是 |
max_count | i64 | 单次请求返回的最大结果数。默认值为 10，最大值为 50。 | 20 | 否 |
search_id | 字符串 (String) | search_id 是系统为缓存的查询结果分配的唯一标识符。后续查询时，可以使用该 search_id，根据相同的查询条件继续检索更多结果。 | "eyJsYXN0X3NvcnQiOlsyNTQxMTkwLCIzNDk1NzA4NjI0N" | 否 |
数据结构
RequestFilters
Key | 类型 | 描述 | 示例 | 是否必填 |
content_published_date_range | DateRange | 商业内容的发布时间范围。 “min”值所代表的日期必须晚于 2022 年 10 月 1 日。 | { "min": 20230102, "max": 20230109 } | 是 |
creator_country_code | 字符串 (String) | 商业内容作者所在的国家/地区。默认值为 ALL。 支持的国家/地区：欧洲经济区 (EEA) 内的国家/地区。请参见支持的国家/地区。 注意：此 API 不适用于英国和瑞士。 | FR | 否 |
creator_usernames | list<string> | 商业内容的创作者。 | [ "joe123", "emma_lol" ] | 否 |
DateRange
Key | 类型 | 描述 | 示例 | 是否必填 |
min | 字符串 (String) | 查询范围的起始日期，该日期必须晚于 2022 年 10 月 1 日。 | 20230102 | 是 |
max | 字符串 (String) | 查询范围的结束日期。 | 20230109 | 是 |
请求示例
curl -L -X POST 'https://open.tiktokapis.com/v2/research/adlib/commercial_content/query/?fields=id,videos' \
-H 'Authorization: bearer clt.example12345Example12345Example' \
-H 'Content-Type: application/json' \
--data-raw '{
"filters":{
"content_published_date_range": {
"min": "20260301",
"max": "20260401"
},
"creator_usernames": ["razaoautomovel"]
}
}'响应
Key | 类型 | 示例 |
data | QueryCommercialContentData | 请参见以下响应示例。 |
error | ErrorStructV2 | 请参见以下响应示例。 |
响应示例
{
"data": {
"commercial_contents": [
{
"brand_names": [
"My Awesome Co.",
"HelloWorld Inc."
],
"create_date": "20230109",
"create_timestamp": 1696875852,
"creator": {
"username": "joe1234567"
},
"id": "v09044g40000ce6enu3c77u36l73sp20",
"label": "Paid partnership",
"videos": [
{
"cover_image_url": "https://asdfcdn.com/17392712.jpeg?x-expires=1679169600\u0026x-signature=asdf",
"url":"https://www.tiktok.com/@joe1234567/video/19384729204821234"
}
]
}
],
"has_more": "true",
"search_id": "2837438294054038"
},
"error": {
"code": "ok",
"http_status_code": 200,
"log_id": "202207280326050102231031430C7E754E",
"message": ""
}
}数据结构
QueryCommercialContentData
Key | 类型 | 描述 | 示例 |
commercial_contents | list<CommercialContent> | 商业内容列表。 | |
has_more | 布尔值 (Boolean) | 表示是否还有更多待返回的条目。 | true |
search_id | 字符串 (String) | search_id 是系统为缓存的查询结果分配的唯一标识符。后续查询时，可以使用该 search_id，根据相同的查询条件继续检索更多结果。 如果后续查询时，要更新请求中的 | "eyJsYXN0X3NvcnQiOlsyNTQxMTkwLCIzNDk1NzA4NjI0N" |
CommercialContent
Key | 类型 | 描述 | 示例 |
id | i64 | The commercial content ID. | 38267490502373 |
create_date | 字符串 (String) | 该商业内容的创建日期，格式为 YYYYMMDD。 | 20230109 |
create_timestamp | i64 | 该商业内容的创建日期，格式为 Unix 时间戳。 | 1696875852 |
label | 字符串 (String) | 该商业内容的标签。 | 品牌合作 |
brand_names | list<string> | 赞助此商业内容的品牌。 | [ "My Awesome Co.", "HelloWorld Inc." ] |
creator | CommercialContentCreator | 该商业内容创作者的公开信息。 | |
video | CommercialContentVideo | 该商业内容视频的公开信息。 |
CommercialContentCreator
Key | 类型 | 描述 | 示例 |
username | 字符串 (String) | 商业内容创作者的 TikTok 用户名。 | joe123 |
CommercialContentVideo
Key | 类型 | 描述 | 示例 |
id | i64 | The commercial content video's ID. | 19384729204821234 |
status | 字符串 (String) | 该商业内容视频的状态。 | active |
url | 字符串 (String) | 该商业内容视频的 URL。 | https://www.tiktok.com/@joe1234567/video/19384729204821234 |
cover_image_url | 字符串 (String) | 该商业内容视频封面图片的 URL。 | https://asdfcdn.com/17392712.jpeg?x-expires=1679169600\u0026x-signature=asdf |
ErrorStructV2
Key | 类型 | 描述 | 示例 |
code | 字符串 (String) | 字符串格式的错误类别代码。 | ok |
message | 字符串 (String) | 详细的错误描述。 | |
log_id | 字符串 (String) | 与对应请求关联的唯一日志 ID，用于错误处理。 | 202207280326050102231031430C7E754E |
http_status_code | i32 | HTTP 状态码。 | 200 |