> ## 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 Transparency API

> Analysieren Sie die Anzeigen Ihrer Wettbewerber aus dem Google Ads Transparency Center als JSON: Listen Sie die Search-, YouTube-, Display-, Play-, Maps- und Shopping-Anzeigen eines Werbetreibenden mit der Laufzeit jeder Anzeige auf und öffnen Sie eine Anzeige für ihren Text, ihr Video und ihre Impressionen nach Land.

Lesen Sie das Google Ads Transparency Center über die asynchrone Task-API als JSON, um zu sehen, welche Google-Anzeigen Ihre Wettbewerber schalten. ADS ist eine eigene Engine: Senden Sie `taskType` `ADS` mit `platform` `google_ads_transparency`, und `action` wählt, was gelesen wird. Die Bibliothek deckt Anzeigen auf Google Search, YouTube, Display, Google Play, Maps und Shopping in jedem Land ab. Zur Auswahl zwischen den Werbebibliotheken siehe [Werbebibliotheken im Vergleich](https://docs.querying.ai/de/engines/ad-libraries.md).

* `search` (Standard) listet die Anzeigen eines Werbetreibenden mit `advertiserId`, mehrerer Wettbewerber gleichzeitig mit `advertiserIds` oder aller Werbetreibenden, deren Anzeigen auf eine Website verlinken, mit `domain` auf. Jede Anzeige enthält ihr Format, ihren ersten und letzten Ausspielungstag und wie viele Tage sie lief, und die Antwort endet mit einer `summary` der gelieferten Anzeigen.
* `advertisers` findet die `advertiserId` eines Werbetreibenden anhand seines Namens.
* `ad` öffnet eine Anzeige: ihren Text, ihr Video und ihre Zielseite und, soweit die Bibliothek sie veröffentlicht, die Impressionen nach Land und nach Google-Oberfläche.

Eine Suche kostet **0.5 Credits je 30 Anzeigen**, die sie liefert. `advertisers` und `ad` kosten je 0.5 Credits.

## Anfrage

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

Senden Sie den Task ab und fragen Sie dann `GET /v1/async/task/{id}` ab oder empfangen Sie den Webhook. Siehe [Asynchrone Tasks](https://docs.querying.ai/de/concepts/async-tasks.md).

## Anzeigen eines Wettbewerbers analysieren

Vier Anfragen decken eine Wettbewerbsanalyse ab:

1. `advertisers` mit dem Namen des Wettbewerbers liefert dessen `advertiserId` und die Websites, die die Bibliothek für den Namen vorschlägt.
2. `search` mit dieser `advertiserId` oder mit der `domain` des Wettbewerbers listet seine Anzeigen auf. `activeDays` zeigt, welche Anzeigen am längsten laufen, `mediaType` und `publisherPlatforms` gliedern die Anzeigen nach Creative und Oberfläche, und `summary` zählt die Formate und die Anzeigen, die in jeder Woche gestartet sind.
3. `ad` mit der `libraryId` und der `advertiserId` einer Anzeige liefert ihren Text, ihr Video, die erreichten Länder und, bei in der EU ausgespielten Anzeigen, ihre Impressionen nach Land und Oberfläche.
4. `search` mit `advertiserIds` vergleicht bis zu 10 Wettbewerber in einer Anfrage.

## Parameter

* `action`: `search` (Standard), `advertisers` oder `ad`.
* `query`: Der Name eines Werbetreibenden, 1 bis 100 Zeichen. `advertisers` verlangt ihn, und `search` und `ad` lehnen ihn ab.
* `advertiserId`: Die ID eines Werbetreibenden, etwa `AR16396071307843731457`. `search` braucht `advertiserId`, `advertiserIds` oder `domain`, und `ad` verlangt `advertiserId`.
* `advertiserIds`: 1 bis 10 Werbetreibenden-IDs als Array oder kommagetrennter Text. Senden Sie in einer Anfrage `advertiserIds` oder `advertiserId`.
* `domain`: Eine reine Domain wie `nike.com`. `search` listet die Anzeigen auf, die darauf verlinken, unabhängig davon, welcher Werbetreibende sie schaltet. `domain` und die Werbetreibenden-IDs schließen sich gegenseitig aus.
* `libraryId`: Die Creative-ID einer Anzeige, etwa `CR07264436911983296513`. `ad` verlangt sie.
* `country`: Wo die Anzeigen ausgespielt wurden, als zweistelliger Ländercode, oder `ALL` für alle Länder (Standard). Jeweils ein Land. `search` liest es.
* `publisherPlatforms`: Wo die Anzeigen liefen: `search`, `youtube`, `maps`, `shopping` oder `play`. Jeweils ein Wert.
* `mediaType`: `all` (Standard), `text`, `image` oder `video`.
* `startDate`, `endDate`: `YYYY-MM-DD`, gemeinsam zu senden. Behält die Anzeigen, die zwischen den beiden Tagen mindestens einmal ausgespielt wurden.
* `limit`: 1 bis 500 Anzeigen bei `search` (Standard 30), 1 bis 50 Werbetreibende bei `advertisers` (Standard 30).
* `cursor`: Der `nextCursor` einer früheren Antwort, um die darauffolgenden Anzeigen zu lesen.

`search` liest `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType`, `startDate`, `endDate`, `limit` und `cursor`. `advertisers` liest `query` und `limit`, und `ad` liest `advertiserId` und `libraryId`. Ein Feld, das die Bibliothek nicht durchsuchen kann, etwa `pageId`, `activeStatus` oder `sortBy`, oder ein Feld, das die Aktion nicht liest, wird mit `400 VALIDATION_ERROR` abgelehnt, und `details` nennt das Feld.

## Wettbewerber vergleichen

`advertiserIds` listet die Anzeigen von bis zu 10 Werbetreibenden in einer Anfrage auf. Die `summary` der Antwort zählt die Anzeigen jedes Werbetreibenden, sodass eine Anfrage zeigt, wer die meisten Anzeigen schaltet.

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

## Weitere Anzeigen lesen

Eine Seite der Bibliothek enthält bis zu 100 Anzeigen, daher liest ein `limit` über 100 mehrere Seiten in einer Anfrage. Eine Antwort mit weiteren zu lesenden Anzeigen enthält `nextCursor`. Senden Sie ihn mit derselben Suche als `cursor`, um die nächsten Anzeigen zu erhalten, wieder bis zu `limit`. `nextCursor` ist `null`, sobald die Bibliothek keine weiteren hat.

Ein Cursor funktioniert nur mit der Suche, die ihn geliefert hat: Eine andere `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType` oder ein anderer Datumsbereich wird mit `400 VALIDATION_ERROR` abgelehnt, während sich `limit` ändern darf.

## Werbetreibenden finden

`action` `advertisers` liefert die Werbetreibenden, deren Namen auf `query` passen, so wie das Suchfeld der Bibliothek sie vorschlägt. Senden Sie die gewählte `advertiserId`, um die Anzeigen dieses Werbetreibenden zu suchen.

```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": []
}
```

Jeder Werbetreibende hat `advertiserId`, `advertiserName`, `country` (wo der Werbetreibende registriert ist), `verified`, `adCountRange` (die Spanne der Anzeigen des Werbetreibenden laut Bibliothek, `min` und `max`) und `libraryUrl`, die den Werbetreibenden im Transparency Center öffnet. `adCount` ist `null`, weil die Bibliothek eine Spanne liefert. `domains` listet die Websites, die die Bibliothek für den Namen vorschlägt und die `search` als `domain` annimmt. Ein Name, den kein Werbetreibender trägt, endet mit leerem `advertisers`. Eine Werbetreibenden-Suche nimmt nur `query` und `limit` an und kostet 0.5 Credits.

## Such-Antwort

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

* Die Antwort gibt `platform`, `action`, `country`, `advertiserId`, `advertiserIds` oder `domain` und die erhaltenen Filter zurück.
* `totalCountRange` ist die Schätzung der Bibliothek für die passenden Anzeigen, als `min` und `max`. `totalCount` ist `null`. `returnedCount` zählt die Anzeigen in `ads`, `hasMore` ist `true`, wenn die Bibliothek mehr hat, die `nextCursor` liest, und `libraryUrl` öffnet dieselbe Suche im Transparency Center.
* Jede Anzeige hat `position`, `libraryId`, `libraryUrl`, `advertiserId`, `advertiserName`, `format` (`TEXT`, `IMAGE` oder `VIDEO`), `width`, `height`, `images`, `videos`, `startDate`, `endDate`, `activeDays`, `isActive` und `landingDomain`.
* `startDate` und `endDate` sind der erste und der letzte Tag, an dem die Bibliothek die Anzeige zeigt (Tage in UTC). `activeDays` zählt die Tage von `startDate` bis `endDate`, beide mitgezählt, und ist `null`, wenn die Bibliothek kein `startDate` liefert. `isActive` ist `true` für eine Anzeige, die zuletzt heute oder gestern ausgespielt wurde, weil die Bibliothek veröffentlicht, wann eine Anzeige zuletzt ausgespielt wurde, und nicht, ob sie läuft.
* `landingDomain` ist der Host der Zielseite der Anzeige, in Kleinbuchstaben und ohne `www.`, und `null`, wo die Bibliothek keinen liefert.
* Viele Textanzeigen kommen als Bild: `images` enthält einen Link zur Anzeige, wie die Bibliothek sie darstellt, und der Text steht in `ad`. `title`, `body`, `ctaText` und `linkUrl` sind in einer Suche `null` und werden von `ad` gefüllt, wenn die Vorschau der Anzeige sie enthält. `impressions` wird von `ad` für in der EU ausgespielte Anzeigen gefüllt. `platforms`, `targeting`, `payer` und `utm` sind `null`.
* `summary` zählt die Anzeigen dieser Antwort: `ads`, `activeAds`, `advertisers` (die 10 mit den meisten Anzeigen: `advertiserId`, `advertiserName`, `ads`), `formats`, `landingDomains` (die 10 mit den meisten Anzeigen), `oldestStartDate`, `newestStartDate` und `medianActiveDays`. Es enthält außerdem `launchesByWeek` (die Anzeigen, die in jeder ISO-Woche starteten, älteste Woche zuerst) und `longestRunning` (die 5 Anzeigen mit den meisten `activeDays`). Eine Suche mit `limit` 500 fasst 500 Anzeigen zusammen, und jede mit `cursor` gelesene Seite enthält die Zusammenfassung ihrer eigenen Anzeigen.
* Bild-Links von Anzeigen (`tpc.googlesyndication.com`) sind nicht signiert und bleiben offen. Die Vorschau-Links von `ad` sind signiert und können ablaufen.
* Eine Suche ohne passende Anzeigen endet mit leerem `ads` und einer `summary` mit `0` Anzeigen.

## Was die Bibliothek aufbewahrt

* Die Bibliothek zeigt Anzeigen aus jedem Land. Eine Anzeige bleibt etwa 12 Monate nach dem letzten Tag, an dem sie ausgespielt wurde, erhalten.
* In der EU ausgespielte Anzeigen enthalten Impressionen: eine Spanne für die Anzeige, für jedes Land mit seinem ersten und letzten Ausspielungstag und für jede Google-Oberfläche. Anderswo ausgespielte Anzeigen enthalten die Länder, die die Anzeige erreichte, und den letzten Ausspielungstag. Bei ihnen liest `ad` den ersten Ausspielungstag (und `activeDays`) aus der Anzeigenliste des Werbetreibenden, denselben Wert, den `search` liefert, und lässt `startDate` und `activeDays` nur dann `null`, wenn die Anzeige nicht unter den ersten 800 Anzeigen der Liste für das erreichte Land steht; `debug.dates` ist `detail`, `search` oder `not-found`.

Um den Anzeigenverlauf eines Wettbewerbers festzuhalten, suchen Sie seine Anzeigen regelmäßig, etwa täglich, und speichern Sie sie.

## Eine Anzeige öffnen

`action` `ad` öffnet die Anzeige mit der `libraryId` und der `advertiserId`, die Sie senden und die beide aus einer Suche stammen. Sie liefert die Anzeige, ihren Werbetreibenden und die Transparenzdaten, die die Bibliothek für sie veröffentlicht.

```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` enthält die Felder einer Suchanzeige sowie den Text aus der Vorschau der Anzeige: `title`, `body`, `ctaText`, `displayUrl`, `linkUrl`, `longTitle`, `channelName`, `address` und `merchant`, jeweils wo die Anzeige es hat, und `videos` (`url`, `previewUrl`). `previewKind` nennt die Art der Anzeige: `text` (Search), `local` (Maps, mit `address`), `display` (Display und YouTube) oder `shopping` (mit `merchant`). `previewText` listet die Texte der Vorschau, und `previewUrl` öffnet sie.
* `reachedCountries` listet die Länder, in denen die Anzeige ausgespielt wurde, als ISO-Codes.
* `impressions` (`min`, `max`) ist die Impressionen-Spanne, die die Bibliothek für in der EU ausgespielte Anzeigen veröffentlicht. Außerhalb der EU ist sie `null`.
* `advertiser` enthält `advertiserId`, `advertiserName` und `libraryUrl`.
* `transparency` enthält `startDate`, `endDate` und `impressions` der Anzeige, ihre `surfaces` (`surfaceId` und die Impressionen-Spanne jeder Google-Oberfläche; `platform` nennt eine Oberfläche nur, wo sie bekannt ist: `SEARCH` und `MAPS`) und ihre `countries`, jeweils mit eigenen `startDate`, `endDate`, `impressions` und `surfaces`. Bei einer außerhalb der EU ausgespielten Anzeige listet `transparency` die Länder mit ihrem letzten Ausspielungstag, und die Daten und Impressionen, die die Bibliothek nur für die EU liefert, sind dort `null` (das eigene `startDate` der Anzeige wird stattdessen aus der Anzeigenliste gelesen).
* `variants` listet die Darstellungen der Anzeige, die die Bibliothek aufbewahrt: `width`, `height`, `imageUrl` und `previewUrl`.
* `platforms` und `targeting` sind `null`, weil die Bibliothek kein Targeting veröffentlicht.
* Eine `libraryId`, zu der die Bibliothek keine Anzeige hat, schlägt mit `PAGE_UNAVAILABLE` fehl.

## Preis

Eine Suche reserviert 0.5 Credits je 30 Anzeigen, die ihr `limit` verlangt, und berechnet 0.5 Credits je 30 gelieferte Anzeigen, mindestens 0.5 Credits. Die Standardsuche mit 30 Anzeigen kostet 0.5 Credits, und eine Suche mit `limit` 500 reserviert 8.5 Credits. `advertisers` und `ad` kosten je 0.5 Credits. Nur abgeschlossene Anfragen werden berechnet.

## Siehe auch

* [Werbebibliotheken im Vergleich](https://docs.querying.ai/de/engines/ad-libraries.md)
* [Meta-Werbebibliothek](https://docs.querying.ai/de/engines/meta-ad-library.md)
* [Engine-Übersicht](https://docs.querying.ai/de/engines/overview.md)
* [Credits und Limits](https://docs.querying.ai/de/concepts/credits-and-limits.md)


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