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つ選びます。このエンドポイントはクエリのリストを受け付けません。
- query と任意の results_limit を /v1/tiktok-ad-library/search に POST します。
- タスクが終了ステータスになるまで /v1/tasks/{task_id} をポーリングします。
- 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.itemsTikTok Ad Library Search API の主なユースケース
- 広告主の広告の発見: 送信した広告主名やブランド名に関連する、対応する公開広告を見つけます。
- キーワード調査: インデックスされたライブラリの内容が1つのトピック語に一致する公開広告を集め、確認用のセットを作成します。
- クリエイティブの全体像の把握: 返されたレコード間で、表示されているテーマ、メディアの参照、広告主のラベル、表示期間を比較します。
- 詳細取得用のキュー作成: 公開広告IDとソースの参照を集め、詳細エンドポイントで選択したレコードを確認できるようにします。
TikTok Ad Library Search API 活用のヒント
- 関連度は上流の一致方式と並び順で決まるため、具体的な広告主名や特徴的なフレーズを使用してください。
- results_limit は12件単位で選んでください。2,000は全体の上限内ですが、12の倍数というルールを満たさないためエラーになります。
- ソースが終了した場合、空のページを返した場合、またはカーソルが重複した場合は、リクエストより少ない件数になることを想定してください。
- ページをまたいだ重複除外は前提にしないでください。一意性が重要な場合は、自身のパイプラインで安定した広告 id を使用してください。
- 推定オーディエンスやインプレッションはソースの定義に従って扱い、コンバージョンや検証済みのパフォーマンスとはみなさないでください。
- 選択した1件のレコードにはAd Detailsエンドポイントを使用してください。Searchには詳細情報で補完するオプションはありません。
関連API
TikTok Ad Library Search API 以外に別の種類の公開TikTok Ad Libraryデータが必要な場合は、これらのAPIをご利用ください。
- TikTok Ad Library Ad API — 既知の公開TikTok広告URL 1件から、正規化されたクリエイティブ、広告主、配信、遷移先、インプレッション、メディア、公開日、取得情報の各フィールドを返します。