> ## 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、地图和购物上投放的广告，附带每条广告的投放时长，并可打开单条广告，获取文案、视频和按国家划分的展示次数。

通过异步 task API 读取 Google Ads 透明度中心，以 JSON 获取竞品投放了哪些 Google 广告。ADS 是独立的引擎。向 `taskType` `ADS` 发送 `platform` `google_ads_transparency`，并用 `action` 选择要读取的内容。资料库涵盖所有国家的 Google 搜索、YouTube、展示广告、Google Play、地图和购物广告。要在各广告资料库之间选择，参见 [广告资料库对比](https://docs.querying.ai/zh/engines/ad-libraries.md)。

* `search`（默认）列出 `advertiserId` 指定的广告主的广告、`advertiserIds` 指定的多个竞品的广告，或 `domain` 指定的网站所链接广告的所有广告主的广告。每条广告带有形式、首次和最后展示的日期以及投放天数，响应末尾附有汇总所返回广告的 `summary`。
* `advertisers` 按名称查找广告主的 `advertiserId`。
* `ad` 打开单条广告：返回广告的文案、视频和落地页，以及资料库公开时按国家和按 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/zh/concepts/async-tasks.md)。

## 分析竞品广告

四个请求即可完成一次竞品分析：

1. 用竞品名称发送 `advertisers`，得到它的 `advertiserId`，以及资料库为该名称建议的网站。
2. 用该 `advertiserId` 或竞品的 `domain` 发送 `search`，列出它的广告。`activeDays` 显示哪些广告投放最久，`mediaType` 和 `publisherPlatforms` 按素材和展示位置划分广告，`summary` 统计各形式的广告数和每周开始投放的广告数。
3. 用广告的 `libraryId` 和 `advertiserId` 发送 `ad`，得到文案、视频、触达的国家，对于在欧盟展示的广告，还有按国家和展示位置划分的展示次数。
4. 用 `advertiserIds` 发送 `search`，一次请求比较最多 10 个竞品。

## 参数

* `action`：`search`（默认）、`advertisers` 或 `ad`。
* `query`：广告主名称，1 到 100 个字符。`advertisers` 必须提供，`search` 和 `ad` 会拒绝。
* `advertiserId`：广告主 ID，例如 `AR16396071307843731457`。`search` 需要 `advertiserId`、`advertiserIds` 或 `domain` 之一，`ad` 必须提供 `advertiserId`。
* `advertiserIds`：1 到 10 个广告主 ID，以数组或逗号分隔的文本发送。一次请求发送 `advertiserIds` 或 `advertiserId` 之一。
* `domain`：纯域名，例如 `nike.com`。`search` 列出链接到该域名的广告，无论由哪个广告主投放。`domain` 与广告主 ID 不能同时使用。
* `libraryId`：广告的素材 ID，例如 `CR07264436911983296513`。`ad` 必须提供。
* `country`：广告展示的国家，用两位国家代码表示，`ALL` 表示所有国家（默认）。一次只能指定一个国家。`search` 读取该字段。
* `publisherPlatforms`：广告投放的位置：`search`、`youtube`、`maps`、`shopping` 或 `play`。一次只能指定一个值。
* `mediaType`：`all`（默认）、`text`、`image` 或 `video`。
* `startDate`、`endDate`：`YYYY-MM-DD`，需同时发送。保留在这两天之间至少展示过一次的广告。
* `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` 在一次请求中列出最多 10 个广告主的广告。响应的 `summary` 统计每个广告主的广告数，因此一次请求就能看出谁投放的广告最多。

```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" } }'
```

## 读取更多广告

资料库的一页最多包含 100 条广告，因此 `limit` 超过 100 时，一次请求会读取多页。还有更多广告可读时，响应带有 `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` 对在欧盟展示的广告由 `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 个月。
* 在欧盟展示的广告带有展示次数：广告整体的范围、每个国家的范围（含首次和最后展示的日期）以及每个 Google 展示位置的范围。在其他地区展示的广告带有触达的国家和最后展示的日期。对于这些广告，`ad` 从广告主的广告列表读取首次展示日期（和 `activeDays`），与 `search` 返回的值相同；只有当广告不在它所触达国家的列表前 800 条广告中时，`startDate` 和 `activeDays` 才为 `null`；`debug.dates` 为 `detail`、`search` 或 `not-found`。

要保留竞品的广告历史，请定期（例如每天）搜索其广告并存储。

## 打开单条广告

`action` `ad` 打开你发送的 `libraryId` 和 `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": "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`）是资料库为在欧盟展示的广告公开的展示次数范围。在欧盟以外为 `null`。
* `advertiser` 包含 `advertiserId`、`advertiserName` 和 `libraryUrl`。
* `transparency` 包含广告的 `startDate`、`endDate` 和 `impressions`，它的 `surfaces`（每个 Google 展示位置的 `surfaceId` 和展示次数范围；`platform` 仅在已知的展示位置 `SEARCH` 和 `MAPS` 上给出名称），以及 `countries`，每个国家各有自己的 `startDate`、`endDate`、`impressions` 和 `surfaces`。对于在欧盟以外展示的广告，`transparency` 列出国家及其最后展示的日期，资料库只为欧盟提供的日期和展示次数在那里为 `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/zh/engines/ad-libraries.md)
* [Meta 广告资料库](https://docs.querying.ai/zh/engines/meta-ad-library.md)
* [引擎概览](https://docs.querying.ai/zh/engines/overview.md)
* [积分与限制](https://docs.querying.ai/zh/concepts/credits-and-limits.md)


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