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 日に最も成果が出た広告を、クリック率、いいね、業種とともに一覧します。市場でどのクリエイティブが効いているかを見るときに使います。
advertisers と ad はリクエストごとに 0.5 クレジットです。
TikTok 広告ライブラリ
リクエスト
GET /v1/async/task/{id} をポーリングするか、webhook で受け取ります。参照: 非同期 task。広告 300 件の検索は約 1 分で完了します。
競合の広告を分析する
3 つのリクエストで競合分析がそろいます。- 競合の名前の先頭部分で
advertisersを送り、ライブラリが把握している正確な名前と ID を受け取ります。 - その名前を
advertiserNameに入れてsearchを送り、広告主の広告を一覧します。sortByは公開日、最終表示日、インプレッションの順に並べ、activeStatusは掲載中または終了した広告だけを残し、summaryは形式ごとの広告数と週ごとに開始した広告数を数えます。 - 広告の
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)を加えます。
libraryId は PAGE_UNAVAILABLE で失敗します。
料金
検索は開始時に、limit が要求した広告 30 件ごとに 0.5 クレジットを保留し、返した広告 30 件ごとに 0.5 クレジットを課金します(最低 0.5 クレジット)。デフォルトの検索(広告 30 件)は 0.5 クレジットで、広告ライブラリでの limit 300 の検索は 5 クレジットを保留します。advertisers と ad はリクエストごとに 0.5 クレジットです。完了したリクエストだけが課金されます。