メインコンテンツへスキップ
TikTok の広告ソースを非同期 task API で読み取り、JSON で受け取ります。ADS は独立したエンジンです。taskType ADS に 2 つのプラットフォームのいずれかを送り、action で読み取る対象を選びます。広告ライブラリを選ぶには、広告ライブラリの比較を参照してください。
  • tiktok_ad_library は TikTok 広告ライブラリ(Commercial Content Library)を読み取ります。EU と EEA の国、英国、スイス、トルコ、ブラジルの 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 分で完了します。

競合の広告を分析する

3 つのリクエストで競合分析がそろいます。
  1. 競合の名前の先頭部分で advertisers を送り、ライブラリが把握している正確な名前と ID を受け取ります。
  2. その名前を advertiserName に入れて search を送り、広告主の広告を一覧します。sortBy は公開日、最終表示日、インプレッションの順に並べ、activeStatus は掲載中または終了した広告だけを残し、summary は形式ごとの広告数と週ごとに開始した広告数を数えます。
  3. 広告の libraryId で ad を送り、ランディングページ、費用の支払者、ターゲティング、オーディエンスの規模、国、年齢、性別ごとのインプレッションを受け取ります。
広告を文面で探すには、advertiserName の代わりに query を使います。テキスト、ハッシュタグ、広告主名を検索します。

パラメーター

  • 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。2 つの日付の間に表示された広告を残します。デフォルトは直近 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 の検索では、2 つのページの境界にある広告が数件、重複したり抜けたりすることがあります。重複は libraryId で見分けます。

広告主を探す

action advertisers は、名前が query で始まる広告主を最大 20 件返します。正確な名前を 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 までの日数で、両方の日を数えます。ライブラリは広告費を示しません。
  • isActive は、activeStatus が active または inactive のとき 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 か月保管します。広告ごとに最初と最後に表示された日とインプレッションの範囲を示します。広告費は公開しません。

広告 1 件を開く

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。Creative Center には広告主の検索がないため、advertisers は 400 VALIDATION_ERROR で拒否されます。
  • 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 は、1 つの国、期間、フィルターの組み合わせに対して広告を最大 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 時間後に失効します。

広告 1 件を開く

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 クレジットです。完了したリクエストだけが課金されます。

関連