> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Ads 透明性センター API

> 競合の広告を Google Ads 透明性センターから JSON で分析します。広告主が Google 検索、YouTube、ディスプレイ、Play、マップ、ショッピングに掲載する広告を、広告ごとの掲載期間とともに一覧し、広告 1 件を開いて文面、動画、国別のインプレッションを受け取ります。

Google Ads 透明性センターを非同期 task API で読み取り、競合がどんな Google 広告を出しているかを JSON で受け取ります。ADS は独立したエンジンです。`taskType` `ADS` に `platform` `google_ads_transparency` を送り、`action` で読み取る対象を選びます。ライブラリは、すべての国の Google 検索、YouTube、ディスプレイ、Google Play、マップ、ショッピングの広告を扱います。広告ライブラリを選ぶには、[広告ライブラリの比較](https://docs.querying.ai/ja/engines/ad-libraries.md)を参照してください。

* `search`(デフォルト)は、`advertiserId` の広告主の広告、`advertiserIds` による複数の競合の広告、または `domain` によるウェブサイトにリンクする広告をすべての広告主から集めて一覧します。広告ごとに形式、最初と最後に表示された日、掲載日数があり、レスポンスの末尾には返した広告をまとめた `summary` が付きます。
* `advertisers` は名前から広告主の `advertiserId` を探します。
* `ad` は広告 1 件を開きます。広告の文面、動画、ランディングページに加え、ライブラリが公開している場合は国別と Google の掲載面別のインプレッションを返します。

検索は返した**広告 30 件ごとに 0.5 クレジット**です。`advertisers` と `ad` はリクエストごとに 0.5 クレジットです。

## リクエスト

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "google_ads_transparency", "domain": "nike.com", "country": "KR", "limit": 5 } }'
```

task を送信したら、`GET /v1/async/task/{id}` をポーリングするか、webhook で受け取ります。参照: [非同期 task](https://docs.querying.ai/ja/concepts/async-tasks.md)。

## 競合の広告を分析する

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 回のリクエストで最も多く広告を出している広告主が分かります。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "google_ads_transparency", "advertiserIds": ["AR16396071307843731457", "<competitor advertiserId>"], "country": "KR", "mediaType": "video" } }'
```

## 広告をさらに取得する

ライブラリの 1 ページには広告が最大 100 件入るため、`limit` が 100 を超えると 1 回のリクエストで複数ページを読み取ります。読み取る広告がさらにある場合、レスポンスに `nextCursor` が付きます。同じ検索にこの値を `cursor` として送ると、次の広告を再び `limit` 件まで受け取れます。ライブラリにこれ以上広告がなければ `nextCursor` は `null` です。

カーソルは、それを返した検索でのみ使えます。`advertiserId`、`advertiserIds`、`domain`、`country`、`publisherPlatforms`、`mediaType` や日付範囲が異なる場合は `400 VALIDATION_ERROR` で拒否され、`limit` は変更できます。

## 広告主を探す

`action` `advertisers` は、広告ライブラリの検索ボックスが提案するように、名前が `query` に一致する広告主を返します。選んだ広告主の `advertiserId` を送ると、その広告主の広告を検索できます。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "google_ads_transparency", "action": "advertisers", "query": "올리브영" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "google_ads_transparency",
  "action": "advertisers",
  "query": "올리브영",
  "returnedCount": 10,
  "libraryUrl": "https://adstransparency.google.com/?region=anywhere",
  "advertisers": [
    {
      "libraryUrl": "https://adstransparency.google.com/advertiser/AR16396071307843731457?region=anywhere",
      "advertiserId": "AR16396071307843731457",
      "advertiserName": "CJ올리브영",
      "country": "KR",
      "verified": false,
      "adCount": null,
      "adCountRange": { "min": 800, "max": 900 }
    }
  ],
  "domains": []
}
```

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

## 検索レスポンスの例

```json theme={"theme":"css-variables"}
{
  "platform": "google_ads_transparency",
  "action": "search",
  "country": "KR",
  "domain": "nike.com",
  "totalCount": null,
  "totalCountRange": { "min": 1000, "max": 2000 },
  "returnedCount": 5,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiZnl5NGtZLXJ2MjBLQkVlcCIsImMiOiJDZ29BUDd6bWZJN0cwNlFURWhDUFRtUGphSW8rNThJRCtROEFBQUFBR2duOCtHUHIrSExRTEM4PSIsInAiOjV9",
  "libraryUrl": "https://adstransparency.google.com/?region=KR&domain=nike.com",
  "ads": [
    {
      "position": 1,
      "libraryId": "CR09172534072340119553",
      "libraryUrl": "https://adstransparency.google.com/advertiser/AR01437837420136497153/creative/CR09172534072340119553?region=anywhere",
      "advertiserId": "AR01437837420136497153",
      "advertiserName": "株式会社ナイキジャパン",
      "isActive": true,
      "startDate": "2025-01-08",
      "endDate": "2026-11-22",
      "activeDays": 684,
      "platforms": null,
      "format": "TEXT",
      "width": 348,
      "height": 517,
      "title": null,
      "body": null,
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": "nike.com",
      "utm": null,
      "payer": null,
      "impressions": null,
      "targeting": null,
      "reachedCountries": null,
      "images": ["https://tpc.googlesyndication.com/archive/simgad/11407271379265753184"],
      "videos": []
    }
  ],
  "summary": {
    "ads": 5,
    "activeAds": 5,
    "advertisers": [
      { "advertiserId": "AR01437837420136497153", "advertiserName": "株式会社ナイキジャパン", "ads": 3 }
    ],
    "formats": { "TEXT": 5 },
    "platforms": {},
    "ctaTypes": {},
    "landingDomains": [
      { "domain": "nike.com", "ads": 5 }
    ],
    "utmCampaigns": [],
    "launchesByWeek": [
      { "week": "2022-W32", "ads": 1 }
    ],
    "longestRunning": [
      {
        "libraryId": "CR16869261615919267841",
        "advertiserName": "NIKE GLOBAL TRADING B.V. SINGAPORE BRANCH",
        "isActive": true,
        "activeDays": 1563,
        "title": null
      }
    ],
    "oldestStartDate": "2022-08-13",
    "newestStartDate": "2025-01-08",
    "medianActiveDays": 714
  }
}
```

* レスポンスは `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 つの値は検索結果から得られます。広告、広告主、ライブラリがその広告に公開する透明性情報を返します。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "google_ads_transparency", "action": "ad", "advertiserId": "AR18378488041124659201", "libraryId": "CR16529691107676651521" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "google_ads_transparency",
  "action": "ad",
  "ad": {
    "libraryId": "CR16529691107676651521",
    "libraryUrl": "https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR16529691107676651521?region=anywhere",
    "advertiserId": "AR18378488041124659201",
    "advertiserName": "Nike Retail BV",
    "isActive": true,
    "startDate": "2025-11-18",
    "endDate": "2026-11-22",
    "activeDays": 370,
    "platforms": null,
    "format": "TEXT",
    "title": "Nike Black Friday Days trwają - Rabat do 40% na wybrane modele",
    "body": "Dni Nike Black Friday Days wystartowały. Zniżki do 40% na wybrane produkty. Do 1 grudnia.",
    "ctaText": null,
    "ctaType": null,
    "linkUrl": null,
    "landingDomain": "nike.com",
    "utm": null,
    "payer": null,
    "impressions": { "min": 9000, "max": 10000 },
    "targeting": null,
    "reachedCountries": ["DE", "PL"],
    "images": [],
    "videos": [],
    "displayUrl": "www.nike.com/kobiety/fleece",
    "previewKind": "text",
    "previewText": ["nike.com", "www.nike.com/kobiety/fleece"],
    "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js"
  },
  "advertiser": {
    "libraryUrl": "https://adstransparency.google.com/advertiser/AR18378488041124659201?region=anywhere",
    "advertiserId": "AR18378488041124659201",
    "advertiserName": "Nike Retail BV"
  },
  "transparency": {
    "startDate": "2025-11-18",
    "endDate": "2026-11-22",
    "impressions": { "min": 9000, "max": 10000 },
    "surfaces": [
      {
        "impressions": { "min": 9000, "max": 10000 },
        "surfaceId": 3,
        "platform": "SEARCH"
      },
      {
        "impressions": { "min": 0, "max": 1000 },
        "surfaceId": 2,
        "platform": "MAPS"
      }
    ],
    "countries": [
      {
        "country": "DE",
        "startDate": "2025-11-24",
        "endDate": "2026-11-22",
        "impressions": { "min": 0, "max": 1000 },
        "surfaces": [
          {
            "impressions": { "min": 0, "max": 1000 },
            "surfaceId": 3,
            "platform": "SEARCH"
          }
        ]
      },
      {
        "country": "PL",
        "startDate": "2025-11-18",
        "endDate": "2026-11-22",
        "impressions": { "min": 9000, "max": 10000 },
        "surfaces": [
          {
            "impressions": { "min": 0, "max": 1000 },
            "surfaceId": 2,
            "platform": "MAPS"
          },
          {
            "impressions": { "min": 9000, "max": 10000 },
            "surfaceId": 3,
            "platform": "SEARCH"
          }
        ]
      }
    ]
  },
  "variants": [
    {
      "width": null,
      "height": null,
      "imageUrl": null,
      "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js"
    },
    {
      "width": null,
      "height": null,
      "imageUrl": null,
      "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js"
    }
  ]
}
```

* `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 クレジットです。完了したリクエストだけが課金されます。

## 関連

* [広告ライブラリの比較](https://docs.querying.ai/ja/engines/ad-libraries.md)
* [Meta 広告ライブラリ](https://docs.querying.ai/ja/engines/meta-ad-library.md)
* [エンジン一覧](https://docs.querying.ai/ja/engines/overview.md)
* [クレジットと上限](https://docs.querying.ai/ja/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.