メインコンテンツへスキップ
Google Ads 透明性センターを非同期 task API で読み取り、競合がどんな Google 広告を出しているかを JSON で受け取ります。ADS は独立したエンジンです。taskType ADS に platform google_ads_transparency を送り、action で読み取る対象を選びます。ライブラリは、すべての国の Google 検索、YouTube、ディスプレイ、Google Play、マップ、ショッピングの広告を扱います。広告ライブラリを選ぶには、広告ライブラリの比較を参照してください。
  • search(デフォルト)は、advertiserId の広告主の広告、advertiserIds による複数の競合の広告、または domain によるウェブサイトにリンクする広告をすべての広告主から集めて一覧します。広告ごとに形式、最初と最後に表示された日、掲載日数があり、レスポンスの末尾には返した広告をまとめた summary が付きます。
  • advertisers は名前から広告主の advertiserId を探します。
  • ad は広告 1 件を開きます。広告の文面、動画、ランディングページに加え、ライブラリが公開している場合は国別と Google の掲載面別のインプレッションを返します。
検索は返した広告 30 件ごとに 0.5 クレジットです。advertisers と ad はリクエストごとに 0.5 クレジットです。

リクエスト

task を送信したら、GET /v1/async/task/{id} をポーリングするか、webhook で受け取ります。参照: 非同期 task。

競合の広告を分析する

4 つのリクエストで競合分析がそろいます。
  1. 競合の名前で advertisers を送り、advertiserId と、ライブラリがその名前に提案するウェブサイトを受け取ります。
  2. その advertiserId または競合の domain で search を送り、広告を一覧します。activeDays は長く掲載している広告を示し、mediaType と publisherPlatforms はクリエイティブと掲載面で広告を分け、summary は形式ごとの広告数と週ごとに開始した広告数を数えます。
  3. 広告の libraryId と advertiserId で ad を送り、文面、動画、到達した国を受け取ります。EU で表示された広告は、国別と掲載面別のインプレッションも受け取れます。
  4. advertiserIds で search を送り、最大 10 の競合を 1 回のリクエストで比較します。

パラメーター

  • action: search(デフォルト)、advertisers、ad。
  • query: 広告主の名前、1〜100 文字。advertisers では必須で、search と ad では拒否されます。
  • advertiserId: 広告主の ID(例: AR16396071307843731457)。search には advertiserId、advertiserIds、domain のいずれかが必要で、ad では advertiserId が必須です。
  • advertiserIds: 広告主 ID 1〜10 件。配列またはカンマ区切りのテキストで送ります。1 回のリクエストでは advertiserIds と advertiserId のどちらか一方を送ります。
  • domain: nike.com のようなドメインのみ。search は、どの広告主が出していても、そのドメインにリンクする広告を一覧します。domain と広告主 ID は同時に使えません。
  • libraryId: 広告のクリエイティブ ID(例: CR07264436911983296513)。ad では必須です。
  • country: 広告が掲載された国の 2 文字コード、またはすべての国を表す ALL(デフォルト)。一度に 1 か国だけ指定できます。search が読み取ります。
  • publisherPlatforms: 広告が掲載された場所: search、youtube、maps、shopping、play。一度に 1 つの値だけ指定できます。
  • mediaType: all(デフォルト)、text、image、video。
  • startDate、endDate: YYYY-MM-DD。2 つを一緒に送ります。2 つの日付の間に 1 回以上表示された広告を残します。
  • limit: search では広告 1〜500 件(デフォルト 30)、advertisers では広告主 1〜50 件(デフォルト 30)。
  • cursor: 前のレスポンスの nextCursor。その後の広告を受け取ります。
search は advertiserId、advertiserIds、domain、country、publisherPlatforms、mediaType、startDate、endDate、limit、cursor を読み取ります。advertisers は query と limit、ad は advertiserId と libraryId を読み取ります。pageId、activeStatus、sortBy のようにライブラリが検索できないフィールドや、アクションが読み取らないフィールドは 400 VALIDATION_ERROR で拒否され、details がそのフィールドを示します。

競合を比較する

advertiserIds は、1 回のリクエストで最大 10 の広告主の広告を一覧します。レスポンスの summary が広告主ごとの広告数を数えるので、1 回のリクエストで最も多く広告を出している広告主が分かります。

広告をさらに取得する

ライブラリの 1 ページには広告が最大 100 件入るため、limit が 100 を超えると 1 回のリクエストで複数ページを読み取ります。読み取る広告がさらにある場合、レスポンスに nextCursor が付きます。同じ検索にこの値を cursor として送ると、次の広告を再び limit 件まで受け取れます。ライブラリにこれ以上広告がなければ nextCursor は null です。 カーソルは、それを返した検索でのみ使えます。advertiserId、advertiserIds、domain、country、publisherPlatforms、mediaType や日付範囲が異なる場合は 400 VALIDATION_ERROR で拒否され、limit は変更できます。

広告主を探す

action advertisers は、広告ライブラリの検索ボックスが提案するように、名前が query に一致する広告主を返します。選んだ広告主の advertiserId を送ると、その広告主の広告を検索できます。
広告主ごとに advertiserId、advertiserName、country(広告主が登録されている国)、verified、adCountRange(ライブラリが示す広告主の広告数の範囲、min と max)、透明性センターでその広告主を開く libraryUrl があります。ライブラリは範囲を示すため adCount は null です。domains はライブラリがその名前に提案するウェブサイトで、search が domain として受け取ります。その名前の広告主がない場合は、空の advertisers で完了します。広告主の検索は query と limit のみ受け付け、0.5 クレジットです。

検索レスポンスの例

  • レスポンスは platform、action、country、advertiserId、advertiserIds または domain、および受け取ったフィルターをそのまま返します。
  • totalCountRange は、ライブラリが推定した条件に合う広告数で、min と max で返ります。totalCount は null です。returnedCount は ads の広告数、hasMore はライブラリにさらに広告があれば true で nextCursor で続きを取得し、libraryUrl は同じ検索を透明性センターで開きます。
  • 広告ごとに position、libraryId、libraryUrl、advertiserId、advertiserName、format(TEXT、IMAGE、VIDEO)、width、height、images、videos、startDate、endDate、activeDays、isActive、landingDomain があります。
  • startDate と endDate は、ライブラリがその広告を最初と最後に表示した日です(UTC の日付)。activeDays は startDate から endDate までの日数で、両方の日を数えます。ライブラリが startDate を示さない場合は null です。ライブラリは広告が最後に表示された時点だけを公開し、掲載中かどうかは示さないため、isActive は今日または昨日に最後に表示された広告で true です。
  • landingDomain は広告のランディングページのホストで、小文字にして www. を除いた値です。ライブラリが示さない場合は null です。
  • 多くのテキスト広告は画像として届きます。images はライブラリが描画した広告へのリンクを持ち、文面は ad にあります。title、body、ctaText、linkUrl は検索では null で、広告のプレビューにある場合に ad が埋めます。impressions は EU で表示された広告について ad が埋めます。platforms、targeting、payer、utm は null です。
  • summary はこのレスポンスの広告を数えます。ads、activeAds、advertisers(広告が最も多い 10 件: advertiserId、advertiserName、ads)、formats、landingDomains(広告が最も多い 10 件)、oldestStartDate、newestStartDate、medianActiveDays です。launchesByWeek(ISO 週ごとに開始した広告数、古い週から)と longestRunning(activeDays が最大の広告 5 件)も持ちます。limit 500 の検索は広告 500 件を要約し、cursor で読む各ページはそのページの広告の要約を持ちます。
  • 広告の画像リンク(tpc.googlesyndication.com)は署名されておらず、開いたままです。ad のプレビューリンクは署名されており、期限切れになることがあります。
  • 条件に合う広告がない検索は、空の ads と広告 0 件の summary で完了します。

ライブラリが保管する範囲

  • ライブラリはすべての国の広告を表示します。広告は最後に表示された日から約 12 か月残ります。
  • EU で表示された広告にはインプレッションがあります。広告全体、国ごと(最初と最後に表示された日を含む)、Google の掲載面ごとの範囲です。それ以外で表示された広告には、広告が到達した国と最後に表示された日があります。この広告では、ad が最初に表示された日(と activeDays)を広告主の広告一覧から読み取り、search が返す値と同じです。広告が到達した国の一覧の先頭 800 件に含まれない場合にだけ startDate と activeDays は null になり、debug.dates は detail、search、not-found のいずれかです。
競合の広告履歴を残すには、その広告を毎日など定期的に検索して保存してください。

広告 1 件を開く

action ad は、送った libraryId と advertiserId の広告を開きます。2 つの値は検索結果から得られます。広告、広告主、ライブラリがその広告に公開する透明性情報を返します。
  • ad は検索広告のフィールドに加えて、広告のプレビューにある文面を持ちます。title、body、ctaText、displayUrl、linkUrl、longTitle、channelName、address、merchant は広告にあるものだけが入り、videos(url、previewUrl)もあります。previewKind は広告の種類です。text(検索)、local(マップ、address あり)、display(ディスプレイと YouTube)、shopping(merchant あり)。previewText はプレビューの文面を並べ、previewUrl はプレビューを開きます。
  • reachedCountries は、広告が表示された国を ISO コードで並べます。
  • impressions(min、max)は、ライブラリが EU で表示された広告に公開するインプレッションの範囲です。EU 外では null です。
  • advertiser は advertiserId、advertiserName、libraryUrl を持ちます。
  • transparency は広告の startDate、endDate、impressions、surfaces(Google の掲載面ごとの surfaceId とインプレッションの範囲。platform は掲載面が判明している SEARCH と MAPS にだけ掲載面名を持ちます)、そしてそれぞれ startDate、endDate、impressions、surfaces を持つ countries を含みます。EU 外で表示された広告の transparency は国と最後に表示された日を並べ、ライブラリが EU にだけ示す日付とインプレッションはそこでは null です(広告自体の startDate は広告一覧から読み取ります)。
  • variants は、ライブラリが保持する広告のレンダリングを並べます。width、height、imageUrl、previewUrl です。
  • ライブラリがターゲティングを公開していないため、platforms と targeting は null です。
  • ライブラリに広告がない libraryId は PAGE_UNAVAILABLE で失敗します。

料金

検索は開始時に、limit が要求した広告 30 件ごとに 0.5 クレジットを保留し、返した広告 30 件ごとに 0.5 クレジットを課金します(最低 0.5 クレジット)。デフォルトの検索(広告 30 件)は 0.5 クレジットで、limit 500 の検索は 8.5 クレジットを保留します。advertisers と ad はリクエストごとに 0.5 クレジットです。完了したリクエストだけが課金されます。

関連