跳转到主要内容
通过异步 task API 以 JSON 读取 TikTok 的广告来源。ADS 是独立的引擎:向 taskType ADS 发送两个平台之一,并用 action 选择要读取的内容。要在各广告资料库之间选择,参见 广告资料库对比。
  • tiktok_ad_library 读取 TikTok 广告资料库(Commercial Content Library)。它列出在 34 个地区展示的广告:欧盟和欧洲经济区国家、英国、瑞士、土耳其和巴西。每条广告带有首次和最后展示的日期以及展示次数范围,ad 另外提供落地页、付费方、定向,以及按国家、年龄、性别划分的展示次数。用它查看竞品的全部广告。
  • tiktok_creative_center 读取 TikTok Creative Center 的热门广告。它列出 28 个国家(包括美国、韩国和日本)在最近 7、30 或 180 天表现最好的广告,附带点击率、点赞数和行业。用它了解哪些素材在某个市场有效。
两个平台的搜索都按返回的每 30 条广告收取 0.5 积分。advertisers 和 ad 每次请求收取 0.5 积分。

TikTok 广告资料库

请求

提交 task 后,轮询 GET /v1/async/task/{id} 或通过 webhook 接收。参见 异步 task。300 条广告的搜索约需一分钟。

分析竞品广告

三个请求即可完成一次竞品分析:
  1. 用竞品名称的开头部分发送 advertisers,得到资料库所知的确切名称和 ID。
  2. 把该名称放入 advertiserName 发送 search,列出该广告主的广告。sortBy 按发布日期、最后展示日期或展示次数排序,activeStatus 只保留投放中或已停止的广告,summary 统计各形式的广告数和每周开始投放的广告数。
  3. 用广告的 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 以及广告背后的 TikTok account(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)。
Creative Center 没有对应广告的 libraryId 会以 PAGE_UNAVAILABLE 失败。

价格

搜索开始时,按 limit 所要求的每 30 条广告预留 0.5 积分,按实际返回的每 30 条广告收取 0.5 积分,最少 0.5 积分。默认搜索(30 条广告)收取 0.5 积分,在广告资料库上 limit 为 300 的搜索预留 5 积分。advertisers 和 ad 每次请求收取 0.5 积分。只对已完成的请求收费。

相关