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件送信して非同期タスクを追跡し、標準の結果エンベロープから正規化広告レコードを読み取ります。
- パスに /creative/ を含む、adstransparency.google.com上のhttpまたはhttpsのURLを1件用意します。
- url を /v1/google-ad-library/ad に POST し、返された task_id を保存します。
- タスクが成功または失敗するまで /v1/tasks/{task_id} をポーリングします。
- 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 itemGoogle Ad Library Ad API の主なユースケース
- 選定したクリエイティブの情報補完: クリエイティブID、広告主の参照、広告文、リンク先、フォーマット、メディア、取得元URLを使って、以前に見つけた広告レコードを補完します。
- 公開配信の根拠の確認: 取得できた期間、国、掲載面、インプレッションを比較し、既知のクリエイティブがいつどこで公開確認されたかを記録します。
- クリエイティブのスナップショット保存: 正規化されたテキスト、メディア、広告主、配信、リンク先、collected_at の各フィールドを保存し、後で特定時点の比較に使います。
Google Ad Library Ad API 活用のヒント
- ホストと /creative/ のパスが検証を通過するよう、CR識別子単体や広告主URLではなく、完全なクリエイティブURLを送信してください。
- 成功したものの項目がないタスクは、プロバイダー側の失敗とは区別して扱ってください。削除された、制限された、または利用できないクリエイティブでは、使用可能なレコードが得られないことがあります。
- 配信、テキスト、リンク先、広告主、インプレッション、メディアの各フィールドは null 許容のまま保持し、欠けている公開値を0や空の情報に変換しないでください。
- 広告の発見や一覧の作成には、Advertiser SearchとCompany Adsを使用してください。この詳細取得は、送信したクリエイティブのみを意図的に照会します。
関連API
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の公開クリエイティブを取得します。トピック、地域、日付、掲載面、フォーマット、取得件数上限を指定できます。