tiktok-ad-library/
search

広告主名またはキーワードのクエリ1つで、対応する公開TikTok広告レコードを検索し、取得可能な場合は正規化された識別情報、表示期間、オーディエンス指標、メディアの参照を取得します。

TikTok Ad Library Search API

広告主名またはキーワード
1ページ12件
公開広告の発見
結果1件あたり0.5クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

TikTok Ad Library Search

TikTok Ad Library Searchは、広告主名またはキーワードのクエリ1つを公開Ads Libraryに送信し、リクエストしたページ単位の上限に達するか、上流で停止条件に達するまで不透明なカーソルをたどります。透明性の調査や広告の発見を目的としており、非公開のキャンペーン管理やパフォーマンス測定には対応していません。

TikTok Ad Library Search API の主な機能

  • 絞り込んだ1つのクエリ必須の空でない広告主名、ブランド名、またはキーワードを1つ指定して検索します。
  • ページ単位の取得12〜2,000件の結果を12の倍数でリクエストします。有効な最大値は1,992です。
  • 不透明なカーソルの処理上限、空のページ、終了シグナル、カーソルの欠落、カーソルの重複のいずれかに達するまで、ソースのカーソルをたどります。
  • 正規化された広告サマリー識別情報、広告主、表示期間、配信、リンク先、インプレッション、メディア、公開日時、取得日時の安定したフィールドを受け取れます。
  • ソースに応じた null の扱い公開検索結果でサマリーのみが公開されている場合や値が省略されている場合は、フィールドを null または空のままにします。

TikTok Ad Library Search API のパラメータ

パラメータ必須説明
query必須必須。空でない広告主名またはキーワードです。指定できるクエリは1つだけです。
results_limit任意任意。結果件数の上限です。デフォルトは12で、12〜2,000の範囲の12の倍数である必要があります。有効な最大値は1,992です。

TikTok Ad Library Search API の使い方

クエリ1つと有効なページ単位の上限を送信し、非同期タスクをポーリングして、正規化された結果ページを読み取ります。

  1. 広告主名またはキーワードを1つ選びます。このエンドポイントはクエリのリストを受け付けません。
  2. query と任意の results_limit を /v1/tiktok-ad-library/search に POST します。
  3. タスクが終了ステータスになるまで /v1/tasks/{task_id} をポーリングします。
  4. data.results.items を読み取り、結果のレスポンスに続きのページがあると示されている場合はタスク結果のカーソルをたどります。
curl -X POST "https://api.socq.ai/v1/tiktok-ad-library/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Anysphere","results_limit":12}'

# Poll GET /v1/tasks/{task_id}
# Read normalized ads from data.results.items

TikTok Ad Library Search API の主なユースケース

  • 広告主の広告の発見: 送信した広告主名やブランド名に関連する、対応する公開広告を見つけます。
  • キーワード調査: インデックスされたライブラリの内容が1つのトピック語に一致する公開広告を集め、確認用のセットを作成します。
  • クリエイティブの全体像の把握: 返されたレコード間で、表示されているテーマ、メディアの参照、広告主のラベル、表示期間を比較します。
  • 詳細取得用のキュー作成: 公開広告IDとソースの参照を集め、詳細エンドポイントで選択したレコードを確認できるようにします。

TikTok Ad Library Search API 活用のヒント

  • 関連度は上流の一致方式と並び順で決まるため、具体的な広告主名や特徴的なフレーズを使用してください。
  • results_limit は12件単位で選んでください。2,000は全体の上限内ですが、12の倍数というルールを満たさないためエラーになります。
  • ソースが終了した場合、空のページを返した場合、またはカーソルが重複した場合は、リクエストより少ない件数になることを想定してください。
  • ページをまたいだ重複除外は前提にしないでください。一意性が重要な場合は、自身のパイプラインで安定した広告 id を使用してください。
  • 推定オーディエンスやインプレッションはソースの定義に従って扱い、コンバージョンや検証済みのパフォーマンスとはみなさないでください。
  • 選択した1件のレコードにはAd Detailsエンドポイントを使用してください。Searchには詳細情報で補完するオプションはありません。

TikTok Ad Library Search API 以外に別の種類の公開TikTok Ad Libraryデータが必要な場合は、これらのAPIをご利用ください。

  • TikTok Ad Library Ad API — 既知の公開TikTok広告URL 1件から、正規化されたクリエイティブ、広告主、配信、遷移先、インプレッション、メディア、公開日、取得情報の各フィールドを返します。

他のプラットフォームを見る

TikTok Ad Libraryのデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

TikTok Ad Library Search API — よくある質問

TikTok Ad Library Search APIは、広告主名またはキーワードのクエリ1つで対応する公開TikTok広告レコードを検索し、ページ単位の上限まで正規化された広告サマリーを返すプログラムインターフェースです。

query は必須の空でない文字列1つです。広告主名、ブランド名、キーワードのいずれかを指定できますが、1回のリクエストで複数のクエリ値は受け付けません。

デフォルトは12です。値は12〜2,000の整数で、かつ12の倍数である必要があるため、有効な上限の最大値は1,992です。

できません。現在のSocQの仕様で受け付けるのは query と results_limit のみで、一致方式、並び順、地域、ソースの対象範囲は上流で制御されます。

リクエストした上限に達した場合、またはソースが広告を返さない、最終ページであると報告する、カーソルを省略する、カーソルが重複する場合に取得は停止します。表示や地域に関するルールによって取得可否が変わることもあります。

取得処理はカーソルのループを防ぎますが、ページをまたいだレコードの重複除外は保証しません。必要な場合は、下流で null でない広告 id を使って重複を除外してください。

返された広告レコード1件につき0.5 SocQクレジットで、基本料金はかかりません。デフォルトの見積もりは結果12件分で、結果が空の場合は結果の料金はかかりません。