taskType ADS 发送两个平台之一,并用 action 选择要读取的内容。要在各广告资料库之间选择,参见 广告资料库对比。
tiktok_ad_library读取 TikTok 广告资料库(Commercial Content Library)。它列出在 34 个地区展示的广告:欧盟和欧洲经济区国家、英国、瑞士、土耳其和巴西。每条广告带有首次和最后展示的日期以及展示次数范围,ad另外提供落地页、付费方、定向,以及按国家、年龄、性别划分的展示次数。用它查看竞品的全部广告。tiktok_creative_center读取 TikTok Creative Center 的热门广告。它列出 28 个国家(包括美国、韩国和日本)在最近 7、30 或 180 天表现最好的广告,附带点击率、点赞数和行业。用它了解哪些素材在某个市场有效。
advertisers 和 ad 每次请求收取 0.5 积分。
TikTok 广告资料库
请求
GET /v1/async/task/{id} 或通过 webhook 接收。参见 异步 task。300 条广告的搜索约需一分钟。
分析竞品广告
三个请求即可完成一次竞品分析:- 用竞品名称的开头部分发送
advertisers,得到资料库所知的确切名称和 ID。 - 把该名称放入
advertiserName发送search,列出该广告主的广告。sortBy按发布日期、最后展示日期或展示次数排序,activeStatus只保留投放中或已停止的广告,summary统计各形式的广告数和每周开始投放的广告数。 - 用广告的
libraryId发送ad,得到落地页、付费方、定向、受众规模,以及按国家、年龄、性别划分的展示次数。
query 代替 advertiserName:它搜索文案、话题标签和广告主名称。
参数
action:search(默认)、advertisers或ad。country:所有操作都必须提供。取值为AT,BE,BG,BR,CH,CY,CZ,DE,DK,EE,ES,FI,FR,GB,GR,HR,HU,IE,IS,IT,LI,LT,LU,LV,MT,NL,NO,PL,PT,RO,SE,SI,SK,TR之一。ALL以及列表之外的国家(如US、KR和JP)会以400 VALIDATION_ERROR拒绝,因为资料库只覆盖这些地区。query:关键词。在search上,它按相关度匹配文案、话题标签和广告主,资料库最多统计 5,000 条广告。在advertisers上,它是广告主名称的开头部分,且必须提供。search需要query或advertiserName,不能同时提供。advertiserName:广告主的确切名称,例如NIKE Retail B.V.。资料库统计它的全部广告。libraryId:广告的数字 ID,例如1879578148398450。ad必须提供。activeStatus:all(默认)、active或inactive。mediaType:all(默认)、video或image。startDate、endDate:YYYY-MM-DD。保留在这两天之间展示的广告。默认为最近 365 天。sortBy:published_desc(默认)、published_asc、last_shown_desc、last_shown_asc、impressions_desc或impressions_asc。它适用于advertiserName搜索,query搜索始终按相关度排序。limit:1 到 300 条广告。默认 30。cursor:上一次响应的nextCursor,用于读取其后的广告。
search 读取上面除 libraryId 之外的所有字段。advertisers 读取 query 和 country,ad 读取 libraryId 和 country。资料库无法搜索的值,或该操作不读取的字段,会以 400 VALIDATION_ERROR 拒绝,details 会指明字段。
读取更多广告
还有更多广告可读时,响应带有nextCursor。把它作为 cursor 与同一搜索一起发送,即可收到后续广告,同样最多 limit 条。资料库没有更多广告时,nextCursor 为 null。游标只能用于返回它的那次搜索:query、advertiserName、country、activeStatus、mediaType、日期范围或 sortBy 不同,会以 400 VALIDATION_ERROR 拒绝,而 limit 可以改变。在资料库按相关度排序的 query 搜索中,两页交界处的少数广告可能重复或遗漏;用 libraryId 区分重复项。
查找广告主
action advertisers 最多返回 20 个名称以 query 开头的广告主。把确切名称作为 advertiserName 发送,即可搜索该广告主的广告。
advertiserId 和 advertiserName。资料库的建议不提供更多信息,所以 country、adCount 和 verified 为 null。广告主搜索收取 0.5 积分。
搜索响应示例
- 响应会原样返回
platform、action、country、query或advertiserName、activeStatus、mediaType和sortBy。totalCount是资料库统计的匹配广告数,在query搜索中最多到 5,000。returnedCount统计ads中的广告数,资料库还有更多广告时hasMore为true,可用nextCursor继续读取,libraryUrl在广告资料库中打开同一搜索。 - 每条广告包含
position、libraryId、libraryUrl、advertiserName、title、format(VIDEO、IMAGE或TEXT)、images、videos(url、previewUrl)、startDate、endDate、activeDays、impressions(min、max)、estimatedAudience(资料库给出的范围,如400K-500K)和platforms(TIKTOK)。 startDate和endDate是资料库展示该广告的第一天和最后一天(UTC 日期)。activeDays是从startDate到endDate的天数,两个日期都计入。资料库不提供花费。activeStatus为active或inactive时,isActive为true或false;为all时为null。advertiserId、payer、linkUrl、landingDomain、utm和targeting在搜索中为null,由ad填充。summary统计本次响应中的广告:ads、activeAds、advertisers(广告最多的 10 个)、formats、platforms、oldestStartDate、newestStartDate和medianActiveDays,并包含launchesByWeek(每个 ISO 周开始投放的广告数)和longestRunning(activeDays最大的 5 条广告)。搜索不含落地页,所以没有landingDomains和utmCampaigns。- 图片和视频 URL 已签名,读取后约 5 到 6 小时过期。请自行保存需要的文件。
- 没有匹配广告的搜索会以空的
ads和广告数为0的summary完成。
资料库保留的范围
资料库展示在其 34 个地区投放的广告,并保留约 13 个月。它为每条广告提供首次和最后展示的日期以及展示次数范围,不公开花费。打开单条广告
action ad 打开你发送的 libraryId 和 country 对应的广告。
ad包含搜索广告的字段,外加linkUrl、landingDomain、payer(为广告付费的一方)、category、objective、ctaText、advertiserId、reachedCountries和targeting。targeting包含byCountry(每个国家的ages和genders)、provinces、cities、languages、interests、targetAudienceSize(资料库给出的范围,如15.5M-18.9M)、customAudience、excludesAudience、highSpendingPower、operatingSystems、deviceModels、videoInteractions和creatorInteractions。资料库没有为该广告公开的部分为null或空。advertiser包含advertiserId、advertiserName、payer、registryCountry以及广告背后的 TikTokaccount(username、displayName、verified、followers、accountType、profileUrl、avatarUrl)。transparency包含totalImpressions和byCountry:每个国家的impressions,以及按age和gender划分的breakdowns。- 资料库没有对应广告的
libraryId会以PAGE_UNAVAILABLE失败。
TikTok Creative Center
Creative Center 列出各国的热门广告,即 TikTok 为最近 7、30 或 180 天挑选的广告。它是排名样本,不是广告主的全部广告:广告主名称常常为空,也不提供日期、花费或展示次数。它为每条广告提供点击率、点赞数、成本水平、行业和目标。用它找出哪些开头钩子、形式和产品在某个市场有效。请求
参数
action:search(默认)或ad。advertisers会以400 VALIDATION_ERROR拒绝,因为 Creative Center 没有广告主查找。country:search必须提供。取值为AE,AR,AU,BR,CA,CO,DE,ES,FR,GB,ID,IT,JP,KR,MX,MY,NL,PH,PK,RO,SA,SE,SG,TH,TR,US,VN,ZA之一。ALL会被拒绝。query:关键词。period:7、30(默认)或180天。industry:行业 ID,例如21103000000(Hardware & Electrical),即广告的industry.id所指的值。objective:traffic,app_installs,conversions,video_views,reach,lead_generation,product_sales,app_promotion。adLanguage:语言代码:en,es,ar,vi,th,de,id,pt,fr,ms,nl,ja,it,ro,zh-Hant,ko。adFormat:spark(助推创作者帖子的广告)或non_spark。sortBy:for_you(默认)、impression、ctr、play_2s_rate、play_6s_rate、cvr或like。limit:1 到 200 条广告。默认 30。cursor:上一次响应的nextCursor。libraryId:热门广告的数字 ID。ad必须提供。
search 读取上面除 libraryId 之外的所有字段,ad 只读取 libraryId。对于同一个国家、周期和筛选条件的组合,Creative Center 最多列出约 400 到 500 条广告(totalCount)。
搜索响应示例
- 响应会原样返回
platform、action、country、period、sortBy以及你传入的筛选条件。totalCount是该组合下的热门广告数。 - 每条广告包含
position、libraryId、title、advertiserName(常为null)、format、ctrPercent(以百分比表示的点击率)、costLevel、likes、industry(id、name)、objectives、durationSeconds、width、height、voiceOver、images、videos和videoUrls(按分辨率划分的视频文件,如360p和1080p)。 - Creative Center 不提供
startDate、endDate、impressions或libraryUrl,所以这些字段为null,summary只统计形式、广告主和平台。 - 视频和图片 URL 已签名,读取后约 5 到 6 小时过期。
打开单条广告
action ad 按 libraryId 打开一条热门广告,并增加 linkUrl、landingDomain、reachedCountries、comments、shares 和 source(广告的制作来源,如 TikTok Ads Manager)。
libraryId 会以 PAGE_UNAVAILABLE 失败。
价格
搜索开始时,按limit 所要求的每 30 条广告预留 0.5 积分,按实际返回的每 30 条广告收取 0.5 积分,最少 0.5 积分。默认搜索(30 条广告)收取 0.5 积分,在广告资料库上 limit 为 300 的搜索预留 5 积分。advertisers 和 ad 每次请求收取 0.5 积分。只对已完成的请求收费。