HTTP URL

https://open.tiktokapis.com/v2/research/adlib/ad/query/

HTTP 请求方法

POST

权限范围

research.adlib.basic

Key

类型

描述

示例

是否必填

Authorization

字符串 (String)

TikTok 用户授权的访问令牌，通过 /v2/oauth/token/ 获取。

Bearer clt.example12345Example12345Example

是

Content-Type

字符串 (String)

资源的原始媒体类型。

application/json

是

Key

类型

描述

示例

是否必填

fields

字符串 (String)

请求的字段：

• ad.id
• ad.first_shown_date
• ad.last_shown_date
• ad.status
• ad.status_statement
• ad.videos
• ad.image_urls
• ad.reach
• advertiser.business_id
• advertiser.business_name
• advertiser.paid_for_by

ad.id,ad.first_shown_date,ad.last_shown_date

是

Key

类型

描述

示例

是否必填

filters

RequestFilters

查询使用的筛选条件。

请参见下方“请求示例”中的 filters 设置。

是

search_term

字符串 (String)

搜索词。最大长度限制为 50 个字符。

如果你指定了 “search_term”，则会忽略 “advertiser_business_ids” 指定的筛选条件。

手游

否

search_type

字符串 (String)

搜索类型（不区分大小写）：

• exact_phrase：返回与搜索词完全匹配的结果。默认搜索类型。
• fuzzy_phrase：返回包含任意或全部搜索词（顺序不限）的结果。

fuzzy_phrase

否

max_count

i64

单次请求返回的最大结果数。默认值为 10，最大值为 50。

20

否

search_id

字符串 (String)

search_id 是系统为缓存的查询结果分配的唯一标识符。后续查询时，可以使用该 search_id，根据相同的查询条件继续检索更多结果。

如果后续查询时，需要更新 search_term 或 filters 值发起新搜索，请勿使用 search_id，以免返回非预期的结果。

20230501124205358FF99E4D6D1294A2A7

否

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。

如果你指定了“search_term”，则此筛选条件将被忽略。

[294854736284058, 495736284058473]

否

unique_users_seen_size_range

SizeRange

观看了广告内容的用户数量范围。

{

"min": "10K",

"max": "20K"

}

否

Key

类型

描述

示例

是否必填

min

字符串 (String)

查询范围的起始日期，该日期必须晚于 2022 年 10 月 1 日。

20230102

是

max

字符串 (String)

查询范围的结束日期。

20230109

是

Key

类型

描述

示例

是否必填

min

字符串 (String)

观看人数下限，单位为千 (K)、百万 (M) 或十亿 (B)。

K、M 和 B 前的数字必须是小于 1000 的整数。

有效值示例：0K、120K、2M、1B

无效值示例：2000K、1.1M、1B2M

否

max

字符串 (String)

观看人数上限，单位为千 (K)、百万 (M) 或十亿 (B)

K、M 和 B 前的数字必须是小于 1000 的整数。

该值必须大于 0。

有效值示例：120K、2M、1B

无效值示例：0K、2000K、1.1M、1B2M

否

Key

类型

示例

data

QueryAdData

请参见以下响应示例。

error

ErrorStructV2

请参见以下响应示例。

Key

类型

描述

示例

ads

list<AdDto>

匹配所有条件的广告列表。

has_more

bool

表示是否还有更多待返回的条目。

true

search_id

字符串 (String)

分配给缓存的搜索结果的唯一标识符。后续查询时，可以使用该 search_id，根据相同的查询条件继续检索更多结果。

2837438294054038

Key

类型

描述

示例

ad

Ad

广告的元数据。

advertiser

Advertiser

广告主的元数据。

Key

类型

描述

示例

id

i64

广告 ID。

1923845247192304

first_shown_date

字符串 (String)

该广告首次展示日期。

20210101

last_shown_date

字符串 (String)

该广告最后一次展示的日期。

20210101

status

字符串 (String)

该广告的审计状态：active 或 inactive。

active

videos

list<AdVideo>

广告视频列表。

image_urls

list<string>

广告图片 URL 列表。

[

"https://asdfcdn.com/17392712.jpeg?x-expires=1679169600\u0026x-signature=asdf"

]

reach

Reach

观看了此广告的用户数。

{

"unique_users_seen": "11K"

}

Key

类型

描述

示例

url

字符串 (String)

该广告的视频地址。

https://asdfcdn.com/..../127364jmdfjsa93d8cn30dm2di/?mime_type=video_mp4

Key

类型

描述

示例

unique_users_seen

字符串 (String)

观看了此广告的用户数。

“11K”

Key

类型

描述

示例

business_id

i64

广告主的企业 ID。

1755645247067185

business_name

字符串 (String)

广告主的企业名称。

Awe Food Co.

paid_by

字符串 (String)

广告主的资金来源。

Awe Co.

Key

类型

描述

示例

code

字符串 (String)

字符串格式的错误类别代码。

ok

message

字符串 (String)

详细的错误描述。

log_id

字符串 (String)

与对应请求关联的唯一日志 ID，用于错误处理。

202207280326050102231031430C7E754E

http_status_code

i32

HTTP 状态码。

200