google-ad-library/
company-ads

広告主IDまたはドメインで、フィルターを適用した公開Google広告透明性センターのクリエイティブレコードを一覧取得し、正規化されたクリエイティブID、取得元URL、配信、フォーマット、取得可能な詳細フィールドを返します。

Google Ad Library Company Ads API

広告主の広告一覧
40件単位のページネーション
フィルター可能なクリエイティブ一覧
結果1件あたり0.5クレジット
準備完了
準備完了

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

README

SocQ 編集 · 更新

Google Ad Library Company Ads

Google広告透明性センターのクリエイティブ一覧は、選択した広告主IDまたは企業ドメインから取得でき、公開クエリのフィルターで絞り込めます。この処理では広告ごとの詳細補完が無効になっているため、一覧レベルで最も信頼できる値はクリエイティブ識別子と取得元URLです。

Google Ad Library Company Ads API の主な機能

  • 広告主またはドメインを起点に取得Googleの広告主IDまたは企業ドメインを少なくとも1つ指定します。両方を指定した場合、その組み合わせ方は上流の取得元が決定します。
  • 検証済みの一覧フィルタートピック、地域、期間、Googleの掲載面、またはテキスト・画像・動画のフォーマット値で、公開クリエイティブ一覧を絞り込みます。
  • カーソルによる収集プロバイダーのカーソルを40件単位のページでたどり、指定した40〜2,000件の結果上限、最終ページ、空のページ、または不正な重複カーソルのいずれかに達した時点で停止します。
  • 安定した広告レコード共通の正規化広告形式で返し、一覧レベルで null や空の詳細フィールドはそのまま保持します。クリエイティブ情報を独自に補完することはありません。

Google Ad Library Company Ads API のパラメータ

パラメータ必須説明
domain必須(いずれか1つ以上)lululemon.com のような企業ウェブサイトのドメインです。domain と advertiser_id の少なくとも一方が必須です。ドメインによる一致は複数の広告主レコードにまたがる場合があります。
advertiser_id必須(いずれか1つ以上)Google透明性センターの広告主識別子で、通常は AR で始まります。advertiser_id と domain の少なくとも一方が必須です。
topic任意任意。公開取得元のトピックフィルターで、all または political を指定します。フィルターの動作と対象範囲は取得元の定義に従います。
region任意任意。US などの地域コードで、完全なターゲティング定義ではなく公開クエリの条件として渡されます。
start_date任意任意。YYYY-MM-DD 形式の取得元の日付フィルター(指定日を含む)です。両方の日付を指定する場合、end_date より後の日付は指定できません。
end_date任意任意。YYYY-MM-DD 形式の取得元の日付フィルターです。両方の日付を指定する場合、start_date より前の日付は指定できません。
platform任意任意。Googleの掲載面で、google_maps、google_play、google_search、google_shopping、youtube のいずれかです。
format任意任意。クリエイティブのフォーマットで、text、image、video のいずれかです。似たクリエイティブのバリエーションが別々のレコードとして表示される場合があります。
results_limit任意保存するクリエイティブレコードの最大件数です。デフォルトは40で、40〜2,000の範囲の40の倍数の整数を指定できます。

Google Ad Library Company Ads API の使い方

構造化された広告主の広告一覧リクエストを1件送信して非同期タスクを追跡し、返されたクリエイティブURLを必要に応じて詳細取得に使います。

  1. advertiser_id または domain を選び、比較や収集の目的に必要なフィルターのみを追加します。
  2. results_limit を40の倍数で40〜2,000の範囲に設定し、リクエストを /v1/google-ad-library/company-ads に POST します。
  3. タスクが成功または失敗するまで /v1/tasks/{task_id} をポーリングし、必要に応じて保存済みのタスク結果をページ送りで読み取ります。
  4. IDとクリエイティブURLは一覧レコードとして扱い、より詳細なフィールドが必要な場合は、選んだURLを別の広告詳細取得処理に送信します。
curl -X POST "https://api.socq.ai/v1/google-ad-library/company-ads" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"AR01614014350098432001","region":"US","format":"video","results_limit":80}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and select creative URLs for detail retrieval

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

  • 詳細取得の候補リスト作成: 1つの広告主のクリエイティブIDと公開URLを一覧取得し、関連するレコードだけを選んで詳細リクエストを行います。
  • 確認できるフォーマット構成の比較: 識別子、フィルター、上限件数、収集期間を揃えたうえで、返されたテキスト・画像・動画の一覧レコード数を集計します。
  • 開示されている配信期間の確認: 同等の日付、地域、トピック、Googleの掲載面フィルターで返されたクリエイティブレコードを特定します。これらは非公開のターゲティングデータとしては扱いません。

Google Ad Library Company Ads API 活用のヒント

  • 対象とする透明性センターのエンティティがすでにわかっている場合は、範囲の広いドメインよりも確認済みの advertiser_id を優先してください。
  • クリエイティブ一覧を時系列で比較する場合は、識別子、フィルター、results_limit、収集日を揃えてください。
  • get_ad_details は常に false のため、一覧レベルではテキスト、日付、リンク先、インプレッション、メディアが null または空になることを想定してください。
  • 成功して結果が0件だった場合は、その時点で送信した識別子とフィルターに該当する使用可能なクリエイティブがなかったことを意味します。その企業が一度も広告を出していない証拠とはみなさないでください。

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

  • Google Ad Library Ad API — Transparency Centerの既知の公開クリエイティブ1件をURLから取得し、広告主、広告文、メディア、配信、地域、フォーマット、遷移先、インプレッションの各フィールドを返します。
  • Google Ad Library Advertiser Search API — クエリと任意の地域指定で、Transparency Centerの公開広告主候補を検索し、広告主情報、Webサイト、ロゴ、地域、取得可能な広告数の各フィールドを返します。

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

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

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

Google Ad Library Company Ads APIは、広告主IDまたはドメインと任意のフィルターで、公開Google広告透明性センターのクリエイティブ一覧レコードを取得するためのプログラムインターフェースです。正規化された広告レコードを返し、一般に詳細フィールドよりもクリエイティブIDと公開URLの方が信頼性の高い値となります。

少なくとも一方が必要です。通常は広告主IDの方が正確で、ドメインは複数の公開広告主エンティティにまたがるレコードに一致する場合があります。両方を指定すると、両方の値がまとめて渡されます。

デフォルトは40で、40〜2,000の範囲の40の倍数の整数を指定する必要があります。SocQはプロバイダーのカーソルをたどり、保存する行をその上限で打ち切ります。

一覧リクエストでは常に get_ad_details=false が送信されるためです。スキーマのフィールド定義は維持されますが、欠けているテキスト、メディア、リンク先、配信、インプレッションの値を推測で補うことはありません。

保存されたクリエイティブレコード1件につき0.5 SocQクレジットです。見積もりは40件を想定しており、超過も許容されます。成功して結果が0件だった場合は、設定されている基本料金0クレジットのみがかかります。