TikTok Ad Library Ad
TikTok Ad Library Adは、検索や手動での確認によって条件を満たすURLが得られた後に、既知の公開広告レコードを1件取得します。上流の識別子を1つ導出して正規化された広告を最大1件返し、広告主の検索、キャンペーンの列挙、Ads Managerの非公開パフォーマンスデータの提供は行いません。
TikTok Ad Library Ad API の主な機能
- 既知の広告URLを入力パスに /ad を含む、TikTok公式の http または https URLを1件送信します。
- 識別子の導出最初の id クエリ値を優先し、次に ad_id、その次にパスの最も右にある数値セグメントを使用します。いずれもない場合は、URLがフォールバックとしてプロバイダーに渡されます。
- 単一オブジェクトの詳細上流の詳細オブジェクトを1件リクエストし、対応する広告IDが存在する場合にのみ最大1件のレコードを出力します。
- 正規化された広告フィールド広告主、広告文、日付、国、プラットフォーム、形式、リンク先、インプレッション、メディア、公開日時、取得日時の安定したフィールドを受け取れます。
- null を許容したソースへの忠実性Commercial Content LibraryとCreative Centerのレコードでは公開されるフィールドが異なるため、取得できない値は null のままにします。
TikTok Ad Library Ad API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
url | 必須 | 必須。パスに /ad を含む、TikTok公式の http または https URLを1件指定します。利用可能な id または ad_id のクエリ値、あるいは数値のパスセグメントを含むURLを推奨します。 |
TikTok Ad Library Ad API の使い方
既知の公開広告URLを送信し、非同期タスクをポーリングして、取得できた場合は1件の結果を処理します。
- 可能であれば、id、ad_id、または数値のパス識別子を含むTikTok公式の広告URLを選びます。
- url を /v1/tiktok-ad-library/ad に POST し、返された task_id を保存します。
- タスクが終了ステータスになるまで /v1/tasks/{task_id} をポーリングします。
- 成功したら data.results.items を読み取ります。詳細取得で返されるアイテムは0件または1件です。
curl -X POST "https://api.socq.ai/v1/tiktok-ad-library/ad" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://library.tiktok.com/ads/detail/?id=1871655924410641"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items; the detail operation returns at most one itemTikTok Ad Library Ad API の主なユースケース
- 選択した広告の確認: 検索結果から選んだ広告1件を、現在取得可能な正規化された詳細フィールドに変換します。
- クリエイティブの確認: 既知の広告について、公開されているクリエイティブのテキスト、広告主情報、形式、メディア、リンク先を確認します。
- 透明性のためのアーカイブ: ソースURL、表示期間、配信状況、取得日時とともに公開レコードを1件保存します。
- ライブラリ間の比較: 選択した広告レコード間で、対応する公開メタデータをキャンペーンのパフォーマンスとみなさずに比較します。
TikTok Ad Library Ad API 活用のヒント
- プロバイダーに依存するフォールバック動作を避けるため、数値の id または ad_id のクエリ値が明示されたURLを優先してください。
- URLが有効でも、上流のソースで識別可能な広告オブジェクトが引き続き公開されているとは限りません。
- Ads LibraryとCreative Centerのフィールドは、直接置き換えられるものではなく、それぞれのソースに固有のものとして扱ってください。
- URLは期限切れになったりリダイレクトされたりすることがあるため、メディアやランディングページの参照は適切な利用条件のもとでのみアーカイブしてください。
- 公開されている表示期間やインプレッションから、ターゲティング、広告費、コンバージョン、パフォーマンスを推測しないでください。
- 広告を探す場合は検索エンドポイントを使用してください。この詳細エンドポイントが広告主の広告を列挙することはありません。
関連API
TikTok Ad Library Ad API 以外に別の種類の公開TikTok Ad Libraryデータが必要な場合は、これらのAPIをご利用ください。
- TikTok Ad Library Search API — 広告主名またはキーワード1つで、対応する公開TikTok広告レコードを検索します。取得件数の上限はページ単位で調整されます。