> ## 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.

# API de Google Ads Transparency

> Analysez les publicités de vos concurrents depuis le Google Ads Transparency Center en JSON : listez les publicités Search, YouTube, Display, Play, Maps et Shopping qu’un annonceur diffuse avec la durée de diffusion de chacune, et ouvrez une publicité pour son texte, sa vidéo et ses impressions par pays.

Lisez le Google Ads Transparency Center en JSON via l’API asynchrone de tâches pour voir quelles publicités Google diffusent vos concurrents. ADS est un moteur à part entière : envoyez `taskType` `ADS` avec `platform` `google_ads_transparency`, et `action` choisit ce qu’il faut lire. La bibliothèque couvre les publicités sur Google Search, YouTube, Display, Google Play, Maps et Shopping dans tous les pays. Pour choisir entre les bibliothèques publicitaires, voir [Bibliothèques publicitaires comparées](https://docs.querying.ai/fr/engines/ad-libraries.md).

* `search` (par défaut) liste les publicités d’un annonceur avec `advertiserId`, de plusieurs concurrents à la fois avec `advertiserIds`, ou de tous les annonceurs dont les publicités renvoient vers un site web avec `domain`. Chaque publicité indique son format, son premier et son dernier jour de diffusion et le nombre de jours où elle a été diffusée, et la réponse se termine par un `summary` des publicités renvoyées.
* `advertisers` trouve le `advertiserId` d’un annonceur à partir de son nom.
* `ad` ouvre une publicité : son texte, sa vidéo et sa page de destination, et là où la bibliothèque les publie, les impressions par pays et par surface Google.

Une recherche coûte **0.5 crédit pour 30 publicités** renvoyées. `advertisers` et `ad` coûtent 0.5 crédit chacun.

## Requête

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

Soumettez la tâche, puis interrogez `GET /v1/async/task/{id}` ou recevez son webhook. Voir [Tâches asynchrones](https://docs.querying.ai/fr/concepts/async-tasks.md).

## Analyser les publicités d’un concurrent

Quatre requêtes couvrent une analyse de la concurrence :

1. `advertisers` avec le nom du concurrent renvoie son `advertiserId` et les sites web que la bibliothèque suggère pour ce nom.
2. `search` avec ce `advertiserId`, ou avec le `domain` du concurrent, liste ses publicités. `activeDays` montre quelles publicités sont diffusées depuis le plus longtemps, `mediaType` et `publisherPlatforms` répartissent les publicités par création et par surface, et `summary` compte les formats et les publicités lancées chaque semaine.
3. `ad` avec le `libraryId` et le `advertiserId` d’une publicité renvoie son texte, sa vidéo, les pays qu’elle a touchés et, pour les publicités diffusées dans l’UE, ses impressions par pays et par surface.
4. `search` avec `advertiserIds` compare jusqu’à 10 concurrents en une seule requête.

## Paramètres

* `action` : `search` (par défaut), `advertisers` ou `ad`.
* `query` : le nom d’un annonceur, de 1 à 100 caractères. `advertisers` l’exige, et `search` et `ad` le rejettent.
* `advertiserId` : l’ID d’un annonceur, comme `AR16396071307843731457`. `search` exige `advertiserId`, `advertiserIds` ou `domain`, et `ad` exige `advertiserId`.
* `advertiserIds` : de 1 à 10 IDs d’annonceur, sous forme de tableau ou de texte séparé par des virgules. Envoyez `advertiserIds` ou `advertiserId` dans une même requête.
* `domain` : un domaine simple comme `nike.com`. `search` liste les publicités qui renvoient vers lui, quel que soit l’annonceur qui les diffuse. `domain` et les IDs d’annonceur s’excluent mutuellement.
* `libraryId` : l’ID de création d’une publicité, comme `CR07264436911983296513`. `ad` l’exige.
* `country` : où les publicités ont été diffusées, sous forme de code pays à deux lettres, ou `ALL` pour tous les pays (par défaut). Un seul pays à la fois. `search` le lit.
* `publisherPlatforms` : où les publicités ont été diffusées : `search`, `youtube`, `maps`, `shopping` ou `play`. Une seule valeur à la fois.
* `mediaType` : `all` (par défaut), `text`, `image` ou `video`.
* `startDate`, `endDate` : `YYYY-MM-DD`, envoyés ensemble. Conserve les publicités diffusées au moins une fois entre les deux jours.
* `limit` : de 1 à 500 publicités sur `search` (par défaut 30), de 1 à 50 annonceurs sur `advertisers` (par défaut 30).
* `cursor` : le `nextCursor` d’une réponse précédente, pour lire les publicités suivantes.

`search` lit `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType`, `startDate`, `endDate`, `limit` et `cursor`. `advertisers` lit `query` et `limit`, et `ad` lit `advertiserId` et `libraryId`. Un champ que la bibliothèque ne peut pas rechercher, comme `pageId`, `activeStatus` ou `sortBy`, ou un champ que l’action ne lit pas, est rejeté avec `400 VALIDATION_ERROR`, et `details` nomme le champ.

## Comparer des concurrents

`advertiserIds` liste les publicités de jusqu’à 10 annonceurs en une seule requête. Le `summary` de la réponse compte les publicités de chaque annonceur, si bien qu’une requête montre qui diffuse le plus de publicités.

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

## Lire plus de publicités

Une page de la bibliothèque contient jusqu’à 100 publicités, donc un `limit` supérieur à 100 lit plusieurs pages en une seule requête. Une réponse qui a encore des publicités à lire contient `nextCursor`. Envoyez-le comme `cursor` avec la même recherche pour recevoir les publicités suivantes, là encore jusqu’à `limit`. `nextCursor` vaut `null` lorsque la bibliothèque n’en a plus.

Un curseur ne fonctionne qu’avec la recherche qui l’a renvoyé : un `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType` ou une plage de dates différents est rejeté avec `400 VALIDATION_ERROR`, tandis que `limit` peut changer.

## Trouver un annonceur

`action` `advertisers` renvoie les annonceurs dont le nom correspond à `query`, tels que les suggère la zone de recherche de la bibliothèque. Envoyez le `advertiserId` que vous choisissez pour rechercher les publicités de cet annonceur.

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

Chaque annonceur a `advertiserId`, `advertiserName`, `country` (où l’annonceur est enregistré), `verified`, `adCountRange` (la fourchette de publicités de l’annonceur donnée par la bibliothèque, `min` et `max`) et `libraryUrl`, qui ouvre l’annonceur dans le Transparency Center. `adCount` vaut `null` parce que la bibliothèque donne une fourchette. `domains` liste les sites web que la bibliothèque suggère pour le nom, que `search` accepte comme `domain`. Un nom qu’aucun annonceur ne porte se termine avec `advertisers` vide. Une recherche d’annonceur n’accepte que `query` et `limit`, et coûte 0.5 crédit.

## Réponse de recherche

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

* La réponse reprend `platform`, `action`, `country`, `advertiserId`, `advertiserIds` ou `domain`, et les filtres reçus.
* `totalCountRange` est l’estimation de la bibliothèque pour les publicités correspondantes, sous forme de `min` et `max`. `totalCount` vaut `null`. `returnedCount` compte les publicités dans `ads`, `hasMore` vaut `true` lorsque la bibliothèque en a davantage, ce que `nextCursor` lit, et `libraryUrl` ouvre la même recherche dans le Transparency Center.
* Chaque publicité a `position`, `libraryId`, `libraryUrl`, `advertiserId`, `advertiserName`, `format` (`TEXT`, `IMAGE` ou `VIDEO`), `width`, `height`, `images`, `videos`, `startDate`, `endDate`, `activeDays`, `isActive` et `landingDomain`.
* `startDate` et `endDate` sont le premier et le dernier jour où la bibliothèque montre la publicité (jours en UTC). `activeDays` compte les jours de `startDate` à `endDate`, les deux inclus, et vaut `null` lorsque la bibliothèque ne donne pas `startDate`. `isActive` vaut `true` pour une publicité diffusée pour la dernière fois aujourd’hui ou hier, car la bibliothèque publie la dernière fois qu’une publicité a été diffusée et non si elle est en cours.
* `landingDomain` est l’hôte de la page de destination de la publicité, en minuscules et sans `www.`, et vaut `null` lorsque la bibliothèque n’en donne pas.
* Beaucoup de publicités textuelles arrivent sous forme d’image : `images` contient un lien vers la publicité telle que la bibliothèque la dessine, et le texte se trouve dans `ad`. `title`, `body`, `ctaText` et `linkUrl` valent `null` dans une recherche et sont remplis par `ad` lorsque l’aperçu de la publicité les contient. `impressions` est rempli par `ad` pour les publicités diffusées dans l’UE. `platforms`, `targeting`, `payer` et `utm` valent `null`.
* `summary` compte les publicités de cette réponse : `ads`, `activeAds`, `advertisers` (les 10 qui ont le plus de publicités : `advertiserId`, `advertiserName`, `ads`), `formats`, `landingDomains` (les 10 qui ont le plus de publicités), `oldestStartDate`, `newestStartDate` et `medianActiveDays`. Il contient aussi `launchesByWeek` (les publicités lancées chaque semaine ISO, de la semaine la plus ancienne à la plus récente) et `longestRunning` (les 5 publicités avec le plus de `activeDays`). Une recherche avec `limit` 500 résume 500 publicités, et chaque page lue avec `cursor` porte le résumé de ses propres publicités.
* Les liens d’image des publicités (`tpc.googlesyndication.com`) ne sont pas signés et restent ouverts. Les liens d’aperçu de `ad` sont signés et peuvent expirer.
* Une recherche sans publicité correspondante se termine avec `ads` vide et un `summary` de `0` publicité.

## Ce que la bibliothèque conserve

* La bibliothèque montre les publicités de tous les pays. Une publicité reste environ 12 mois après le dernier jour où elle a été diffusée.
* Les publicités diffusées dans l’UE comportent des impressions : une fourchette pour la publicité, pour chaque pays avec son premier et son dernier jour de diffusion, et pour chaque surface Google. Les publicités diffusées ailleurs comportent les pays que la publicité a touchés et le dernier jour de diffusion. Pour elles, `ad` lit le premier jour de diffusion (et `activeDays`) dans la liste de publicités de l’annonceur, la même valeur que renvoie `search`, et ne laisse `startDate` et `activeDays` à `null` que si la publicité ne figure pas parmi les 800 premières de la liste pour le pays touché ; `debug.dates` vaut `detail`, `search` ou `not-found`.

Pour conserver l’historique des publicités d’un concurrent, recherchez ses publicités à intervalles réguliers, par exemple chaque jour, et enregistrez-les.

## Ouvrir une publicité

`action` `ad` ouvre la publicité avec le `libraryId` et le `advertiserId` que vous envoyez, tous deux issus d’une recherche. Elle renvoie la publicité, son annonceur et la transparence que la bibliothèque publie pour elle.

```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` contient les champs d’une publicité de recherche, plus le texte de l’aperçu de la publicité : `title`, `body`, `ctaText`, `displayUrl`, `linkUrl`, `longTitle`, `channelName`, `address` et `merchant`, chacun lorsque la publicité le possède, et `videos` (`url`, `previewUrl`). `previewKind` nomme le type de publicité : `text` (Search), `local` (Maps, avec `address`), `display` (Display et YouTube) ou `shopping` (avec `merchant`). `previewText` liste les textes de l’aperçu, et `previewUrl` l’ouvre.
* `reachedCountries` liste les pays où la publicité a été diffusée, sous forme de codes ISO.
* `impressions` (`min`, `max`) est la fourchette d’impressions que la bibliothèque publie pour les publicités diffusées dans l’UE. Hors de l’UE, elle vaut `null`.
* `advertiser` contient `advertiserId`, `advertiserName` et `libraryUrl`.
* `transparency` contient `startDate`, `endDate` et `impressions` de la publicité, ses `surfaces` (`surfaceId` et la fourchette d’impressions de chaque surface Google ; `platform` nomme une surface uniquement lorsqu’elle est connue : `SEARCH` et `MAPS`) et ses `countries`, chacun avec ses propres `startDate`, `endDate`, `impressions` et `surfaces`. Pour une publicité diffusée hors de l’UE, `transparency` liste les pays avec leur dernier jour de diffusion, et les dates et impressions que la bibliothèque ne donne que pour l’UE valent `null` à cet endroit (le `startDate` propre à la publicité est lu dans la liste de publicités).
* `variants` liste les rendus de la publicité que la bibliothèque conserve : `width`, `height`, `imageUrl` et `previewUrl`.
* `platforms` et `targeting` valent `null`, car la bibliothèque ne publie aucun ciblage.
* Un `libraryId` pour lequel la bibliothèque n’a aucune publicité échoue avec `PAGE_UNAVAILABLE`.

## Tarif

Une recherche réserve 0.5 crédit pour 30 publicités que demande son `limit`, et facture 0.5 crédit pour 30 publicités renvoyées, avec un minimum de 0.5 crédit. La recherche par défaut de 30 publicités coûte 0.5 crédit, et une recherche avec `limit` 500 réserve 8.5 crédits. `advertisers` et `ad` coûtent 0.5 crédit chacun. Seules les requêtes terminées sont facturées.

## Voir aussi

* [Bibliothèques publicitaires comparées](https://docs.querying.ai/fr/engines/ad-libraries.md)
* [Bibliothèque publicitaire de Meta](https://docs.querying.ai/fr/engines/meta-ad-library.md)
* [Vue d’ensemble des moteurs](https://docs.querying.ai/fr/engines/overview.md)
* [Crédits et limites](https://docs.querying.ai/fr/concepts/credits-and-limits.md)


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