google-ad-library/
ad

正確なURLから公開Google広告透明性センターのクリエイティブを1件取得し、広告主情報、広告文、メディア、配信期間、地域、フォーマット、リンク先、取得可能なインプレッションを正規化レコードとして返します。

Google Ad Library Ad API

クリエイティブURLを直接指定
広告主とメディア
公開配信情報
結果1件あたり0.5クレジット
準備完了
準備完了

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

README

SocQ 編集 · 更新

Google Ad Library Ad

Google広告透明性センターのクリエイティブは、広告主情報、表示される広告文とメディア、リンク先、フォーマット、配信期間、地域、取得可能なインプレッションデータを含む公開広告レコードです。これらの詳細は、クリエイティブの確認、選定した広告の情報補完、配信状況の調査、特定時点のアーカイブ比較に活用できます。

Google Ad Library Ad API の主な機能

  • クリエイティブの直接取得/creative/ を含むadstransparency.google.comのURLを1件照会し、検索に広げることなく、最大1件の正規化公開広告レコードとして返します。
  • 広告主とクリエイティブのフィールドクリエイティブ識別子、公開取得元URL、取得できたテキスト、広告主の参照、リンク先、フォーマットを安定した広告スキーマで返します。
  • 配信状況の情報取得できた開始日と終了日、国、掲載面を保持し、インプレッションは取得元データを安全に正規化できる場合にのみ単一の値として保持します。
  • 正規化されたメディアアセット取得できた画像や動画の参照を、サムネイル、サイズ、再生時間とともに提供し、存在しない任意の値は省略します。

Google Ad Library Ad API のパラメータ

パラメータ必須説明
url必須必須。公開Google広告透明性センターのクリエイティブURLです。スキームはhttpまたはhttps、ホストはadstransparency.google.comで終わり、パスに /creative/ を含む必要があります。

Google Ad Library Ad API の使い方

正確な公開クリエイティブURLを1件送信して非同期タスクを追跡し、標準の結果エンベロープから正規化広告レコードを読み取ります。

  1. パスに /creative/ を含む、adstransparency.google.com上のhttpまたはhttpsのURLを1件用意します。
  2. url を /v1/google-ad-library/ad に POST し、返された task_id を保存します。
  3. タスクが成功または失敗するまで /v1/tasks/{task_id} をポーリングします。
  4. data.results.items を読み取ります。この詳細取得では最大1件しか返らないため、通常 has_more は false、next_cursor は null です。
curl -X POST "https://api.socq.ai/v1/google-ad-library/ad" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10449491775734153217"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items; this detail operation returns at most one item

Google Ad Library Ad API の主なユースケース

  • 選定したクリエイティブの情報補完: クリエイティブID、広告主の参照、広告文、リンク先、フォーマット、メディア、取得元URLを使って、以前に見つけた広告レコードを補完します。
  • 公開配信の根拠の確認: 取得できた期間、国、掲載面、インプレッションを比較し、既知のクリエイティブがいつどこで公開確認されたかを記録します。
  • クリエイティブのスナップショット保存: 正規化されたテキスト、メディア、広告主、配信、リンク先、collected_at の各フィールドを保存し、後で特定時点の比較に使います。

Google Ad Library Ad API 活用のヒント

  • ホストと /creative/ のパスが検証を通過するよう、CR識別子単体や広告主URLではなく、完全なクリエイティブURLを送信してください。
  • 成功したものの項目がないタスクは、プロバイダー側の失敗とは区別して扱ってください。削除された、制限された、または利用できないクリエイティブでは、使用可能なレコードが得られないことがあります。
  • 配信、テキスト、リンク先、広告主、インプレッション、メディアの各フィールドは null 許容のまま保持し、欠けている公開値を0や空の情報に変換しないでください。
  • 広告の発見や一覧の作成には、Advertiser SearchとCompany Adsを使用してください。この詳細取得は、送信したクリエイティブのみを意図的に照会します。

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

  • Google Ad Library Advertiser Search API — クエリと任意の地域指定で、Transparency Centerの公開広告主候補を検索し、広告主情報、Webサイト、ロゴ、地域、取得可能な広告数の各フィールドを返します。
  • Google Ad Library Company Ads API — 企業ドメインまたは広告主IDから、Transparency Centerの公開クリエイティブを取得します。トピック、地域、日付、掲載面、フォーマット、取得件数上限を指定できます。

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

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

Google Ad Library Ad API — よくある質問

Google Ad Library Ad APIは、正確なURLから公開Google広告透明性センターのクリエイティブを1件取得するためのプログラムインターフェースです。正規化された広告主、広告文、メディア、配信、地域、フォーマット、リンク先、取得可能なインプレッションの各フィールドを返します。

ホストがadstransparency.google.comで終わり、パスに /creative/ を含むhttpまたはhttpsのURLを1件送信してください。クリエイティブID単体、広告主URL、ドメイン、検索クエリ、URLのリストは受け付けません。

正規化レコードでは、ID、取得元URL、テキスト、広告主、配信期間、国、プラットフォーム、フォーマット、リンク先、インプレッション、メディア、公開日時、取得日時が定義されています。取得元に依存するフィールドは null 許容で、メディアは空になる場合があります。

有効なクリエイティブURLでも、削除された、制限された、形式が不正な、または現在利用できない公開レコードを指している場合があります。このエンドポイントは、別のクリエイティブで代替したり、リクエストを検索に切り替えたりすることはありません。

返されたレコード1件につき0.5 SocQクレジットです。設定されている空結果ポリシーにより、レコードが返らなかった場合は基本料金の0クレジットのみが請求されます。