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を必要に応じて詳細取得に使います。
- advertiser_id または domain を選び、比較や収集の目的に必要なフィルターのみを追加します。
- results_limit を40の倍数で40〜2,000の範囲に設定し、リクエストを /v1/google-ad-library/company-ads に POST します。
- タスクが成功または失敗するまで /v1/tasks/{task_id} をポーリングし、必要に応じて保存済みのタスク結果をページ送りで読み取ります。
- 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 retrievalGoogle 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件だった場合は、その時点で送信した識別子とフィルターに該当する使用可能なクリエイティブがなかったことを意味します。その企業が一度も広告を出していない証拠とはみなさないでください。
関連API
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サイト、ロゴ、地域、取得可能な広告数の各フィールドを返します。