taskType ADS に platform google_ads_transparency を送り、action で読み取る対象を選びます。ライブラリは、すべての国の Google 検索、YouTube、ディスプレイ、Google Play、マップ、ショッピングの広告を扱います。広告ライブラリを選ぶには、広告ライブラリの比較を参照してください。
search(デフォルト)は、advertiserIdの広告主の広告、advertiserIdsによる複数の競合の広告、またはdomainによるウェブサイトにリンクする広告をすべての広告主から集めて一覧します。広告ごとに形式、最初と最後に表示された日、掲載日数があり、レスポンスの末尾には返した広告をまとめたsummaryが付きます。advertisersは名前から広告主のadvertiserIdを探します。adは広告 1 件を開きます。広告の文面、動画、ランディングページに加え、ライブラリが公開している場合は国別と Google の掲載面別のインプレッションを返します。
advertisers と ad はリクエストごとに 0.5 クレジットです。
リクエスト
GET /v1/async/task/{id} をポーリングするか、webhook で受け取ります。参照: 非同期 task。
競合の広告を分析する
4 つのリクエストで競合分析がそろいます。- 競合の名前で
advertisersを送り、advertiserIdと、ライブラリがその名前に提案するウェブサイトを受け取ります。 - その
advertiserIdまたは競合のdomainでsearchを送り、広告を一覧します。activeDaysは長く掲載している広告を示し、mediaTypeとpublisherPlatformsはクリエイティブと掲載面で広告を分け、summaryは形式ごとの広告数と週ごとに開始した広告数を数えます。 - 広告の
libraryIdとadvertiserIdでadを送り、文面、動画、到達した国を受け取ります。EU で表示された広告は、国別と掲載面別のインプレッションも受け取れます。 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 件)も持ちます。limit500 の検索は広告 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 クレジットです。完了したリクエストだけが課金されます。