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

> Analiza los anuncios de la competencia desde el Google Ads Transparency Center en JSON: lista los anuncios de Search, YouTube, Display, Play, Maps y Shopping que publica un anunciante con los días que lleva activo cada uno, y abre un anuncio para ver su texto, su vídeo y sus impresiones por país.

Lee el Google Ads Transparency Center como JSON a través de la API asíncrona de tareas para ver qué anuncios de Google publica tu competencia. ADS es un motor propio: envía `taskType` `ADS` con `platform` `google_ads_transparency`, y `action` elige qué leer. La biblioteca cubre los anuncios de Google Search, YouTube, Display, Google Play, Maps y Shopping en todos los países. Para elegir entre las bibliotecas de anuncios, consulta [Bibliotecas de anuncios comparadas](https://docs.querying.ai/es/engines/ad-libraries.md).

* `search` (por defecto) lista los anuncios de un anunciante con `advertiserId`, de varios competidores a la vez con `advertiserIds`, o de todos los anunciantes cuyos anuncios enlazan a un sitio web con `domain`. Cada anuncio incluye su formato, su primer y su último día de emisión y cuántos días estuvo activo, y la respuesta termina con un `summary` de los anuncios devueltos.
* `advertisers` encuentra el `advertiserId` de un anunciante por su nombre.
* `ad` abre un anuncio: su texto, su vídeo y su página de destino, y donde la biblioteca lo publica, las impresiones por país y por superficie de Google.

Una búsqueda cuesta **0.5 créditos por cada 30 anuncios** que devuelve. `advertisers` y `ad` cuestan 0.5 créditos cada uno.

## Solicitud

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

Envía la tarea y consulta `GET /v1/async/task/{id}` o recibe su webhook. Consulta [Tareas asíncronas](https://docs.querying.ai/es/concepts/async-tasks.md).

## Analiza los anuncios de un competidor

Cuatro solicitudes cubren un análisis de la competencia:

1. `advertisers` con el nombre del competidor devuelve su `advertiserId` y los sitios web que la biblioteca sugiere para ese nombre.
2. `search` con ese `advertiserId`, o con el `domain` del competidor, lista sus anuncios. `activeDays` muestra qué anuncios llevan más tiempo activos, `mediaType` y `publisherPlatforms` dividen los anuncios por creativo y superficie, y `summary` cuenta los formatos y los anuncios que empezaron cada semana.
3. `ad` con el `libraryId` y el `advertiserId` de un anuncio devuelve su texto, su vídeo, los países que alcanzó y, en los anuncios mostrados en la UE, sus impresiones por país y superficie.
4. `search` con `advertiserIds` compara hasta 10 competidores en una sola solicitud.

## Parámetros

* `action`: `search` (por defecto), `advertisers` o `ad`.
* `query`: El nombre de un anunciante, de 1 a 100 caracteres. `advertisers` lo requiere, y `search` y `ad` lo rechazan.
* `advertiserId`: El ID de un anunciante, como `AR16396071307843731457`. `search` necesita `advertiserId`, `advertiserIds` o `domain`, y `ad` requiere `advertiserId`.
* `advertiserIds`: De 1 a 10 IDs de anunciante, como array o texto separado por comas. Envía `advertiserIds` o `advertiserId` en una misma solicitud.
* `domain`: Un dominio simple como `nike.com`. `search` lista los anuncios que enlazan a él, sea cual sea el anunciante que los publica. `domain` y los IDs de anunciante se excluyen entre sí.
* `libraryId`: El ID de creativo de un anuncio, como `CR07264436911983296513`. `ad` lo requiere.
* `country`: Dónde se mostraron los anuncios, como código de país de dos letras, o `ALL` para todos los países (por defecto). Un país cada vez. `search` lo lee.
* `publisherPlatforms`: Dónde se publicaron los anuncios: `search`, `youtube`, `maps`, `shopping` o `play`. Un valor cada vez.
* `mediaType`: `all` (por defecto), `text`, `image` o `video`.
* `startDate`, `endDate`: `YYYY-MM-DD`, enviados juntos. Conserva los anuncios mostrados al menos una vez entre los dos días.
* `limit`: De 1 a 500 anuncios en `search` (por defecto 30), de 1 a 50 anunciantes en `advertisers` (por defecto 30).
* `cursor`: El `nextCursor` de una respuesta anterior, para leer los anuncios siguientes.

`search` lee `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType`, `startDate`, `endDate`, `limit` y `cursor`. `advertisers` lee `query` y `limit`, y `ad` lee `advertiserId` y `libraryId`. Un campo que la biblioteca no puede buscar, como `pageId`, `activeStatus` o `sortBy`, o un campo que la acción no lee, se rechaza con `400 VALIDATION_ERROR`, y `details` indica el campo.

## Compara competidores

`advertiserIds` lista los anuncios de hasta 10 anunciantes en una sola solicitud. El `summary` de la respuesta cuenta los anuncios de cada anunciante, así que una solicitud muestra quién publica más anuncios.

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

## Leer más anuncios

Una página de la biblioteca contiene hasta 100 anuncios, así que un `limit` superior a 100 lee varias páginas en una sola solicitud. Una respuesta con más anuncios por leer incluye `nextCursor`. Envíalo como `cursor` con la misma búsqueda para recibir los anuncios siguientes, de nuevo hasta `limit`. `nextCursor` es `null` cuando la biblioteca no tiene más.

Un cursor solo funciona con la búsqueda que lo devolvió: un `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType` o rango de fechas distinto se rechaza con `400 VALIDATION_ERROR`, mientras que `limit` puede cambiar.

## Encontrar un anunciante

`action` `advertisers` devuelve los anunciantes cuyos nombres coinciden con `query`, tal como los sugiere el cuadro de búsqueda de la biblioteca. Envía el `advertiserId` que elijas para buscar los anuncios de ese anunciante.

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

Cada anunciante tiene `advertiserId`, `advertiserName`, `country` (donde está registrado el anunciante), `verified`, `adCountRange` (el rango de anuncios del anunciante que da la biblioteca, `min` y `max`) y `libraryUrl`, que abre el anunciante en el Transparency Center. `adCount` es `null` porque la biblioteca da un rango. `domains` lista los sitios web que la biblioteca sugiere para el nombre, que `search` acepta como `domain`. Un nombre que ningún anunciante lleva se completa con `advertisers` vacío. Una búsqueda de anunciantes solo acepta `query` y `limit`, y cuesta 0.5 créditos.

## Respuesta de búsqueda

```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 respuesta devuelve `platform`, `action`, `country`, `advertiserId`, `advertiserIds` o `domain`, y los filtros recibidos.
* `totalCountRange` es la estimación de la biblioteca de los anuncios coincidentes, como `min` y `max`. `totalCount` es `null`. `returnedCount` cuenta los anuncios de `ads`, `hasMore` es `true` cuando la biblioteca tiene más, que `nextCursor` lee, y `libraryUrl` abre la misma búsqueda en el Transparency Center.
* Cada anuncio tiene `position`, `libraryId`, `libraryUrl`, `advertiserId`, `advertiserName`, `format` (`TEXT`, `IMAGE` o `VIDEO`), `width`, `height`, `images`, `videos`, `startDate`, `endDate`, `activeDays`, `isActive` y `landingDomain`.
* `startDate` y `endDate` son el primer y el último día en que la biblioteca muestra el anuncio (días en UTC). `activeDays` cuenta los días desde `startDate` hasta `endDate`, contando ambos, y es `null` cuando la biblioteca no da `startDate`. `isActive` es `true` para un anuncio mostrado por última vez hoy o ayer, porque la biblioteca publica la última vez que se mostró un anuncio y no si sigue en emisión.
* `landingDomain` es el host de la página de destino del anuncio, en minúsculas y sin `www.`, y `null` cuando la biblioteca no da ninguno.
* Muchos anuncios de texto llegan como imagen: `images` contiene un enlace al anuncio tal como lo dibuja la biblioteca, y el texto está en `ad`. `title`, `body`, `ctaText` y `linkUrl` son `null` en una búsqueda y los rellena `ad` cuando la vista previa del anuncio los tiene. `impressions` lo rellena `ad` en los anuncios mostrados en la UE. `platforms`, `targeting`, `payer` y `utm` son `null`.
* `summary` cuenta los anuncios de esta respuesta: `ads`, `activeAds`, `advertisers` (los 10 con más anuncios: `advertiserId`, `advertiserName`, `ads`), `formats`, `landingDomains` (los 10 con más anuncios), `oldestStartDate`, `newestStartDate` y `medianActiveDays`. También incluye `launchesByWeek` (los anuncios que empezaron en cada semana ISO, de la semana más antigua a la más reciente) y `longestRunning` (los 5 anuncios con más `activeDays`). Una búsqueda con `limit` 500 resume 500 anuncios, y cada página que lees con `cursor` incluye el resumen de sus propios anuncios.
* Los enlaces de imagen de los anuncios (`tpc.googlesyndication.com`) no están firmados y siguen abiertos. Los enlaces de vista previa de `ad` están firmados y pueden caducar.
* Una búsqueda sin anuncios coincidentes se completa con `ads` vacío y un `summary` de `0` anuncios.

## Qué conserva la biblioteca

* La biblioteca muestra anuncios de todos los países. Un anuncio permanece unos 12 meses después del último día en que se mostró.
* Los anuncios mostrados en la UE incluyen impresiones: un rango para el anuncio, para cada país con su primer y su último día de emisión, y para cada superficie de Google. Los anuncios mostrados en otros lugares incluyen los países que alcanzó el anuncio y el último día de emisión. Para ellos, `ad` lee el primer día de emisión (y `activeDays`) de la lista de anuncios del anunciante, el mismo valor que devuelve `search`, y deja `startDate` y `activeDays` en `null` solo si el anuncio no está entre los primeros 800 anuncios de la lista para el país que alcanzó; `debug.dates` es `detail`, `search` o `not-found`.

Para conservar el historial de anuncios de un competidor, busca sus anuncios de forma periódica, por ejemplo cada día, y guárdalos.

## Abrir un anuncio

`action` `ad` abre el anuncio con el `libraryId` y el `advertiserId` que envíes, ambos obtenidos de una búsqueda. Devuelve el anuncio, su anunciante y la transparencia que publica la biblioteca para él.

```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` tiene los campos de un anuncio de búsqueda, más el texto de la vista previa del anuncio: `title`, `body`, `ctaText`, `displayUrl`, `linkUrl`, `longTitle`, `channelName`, `address` y `merchant`, cada uno cuando el anuncio lo tiene, y `videos` (`url`, `previewUrl`). `previewKind` indica el tipo de anuncio: `text` (Search), `local` (Maps, con `address`), `display` (Display y YouTube) o `shopping` (con `merchant`). `previewText` lista los textos de la vista previa, y `previewUrl` la abre.
* `reachedCountries` lista los países en los que se mostró el anuncio, como códigos ISO.
* `impressions` (`min`, `max`) es el rango de impresiones que publica la biblioteca para los anuncios mostrados en la UE. Fuera de la UE es `null`.
* `advertiser` tiene `advertiserId`, `advertiserName` y `libraryUrl`.
* `transparency` incluye `startDate`, `endDate` e `impressions` del anuncio, sus `surfaces` (`surfaceId` y el rango de impresiones de cada superficie de Google; `platform` nombra una superficie solo cuando se conoce: `SEARCH` y `MAPS`) y sus `countries`, cada uno con sus propios `startDate`, `endDate`, `impressions` y `surfaces`. En un anuncio mostrado fuera de la UE, `transparency` lista los países con su último día de emisión, y las fechas e impresiones que la biblioteca da solo para la UE son `null` allí (el `startDate` propio del anuncio se lee de la lista de anuncios).
* `variants` lista las versiones renderizadas del anuncio que conserva la biblioteca: `width`, `height`, `imageUrl` y `previewUrl`.
* `platforms` y `targeting` son `null`, porque la biblioteca no publica la segmentación.
* Un `libraryId` para el que la biblioteca no tiene ningún anuncio falla con `PAGE_UNAVAILABLE`.

## Precio

Una búsqueda reserva 0.5 créditos por cada 30 anuncios que pide su `limit`, y cobra 0.5 créditos por cada 30 anuncios que devuelve, con un mínimo de 0.5 créditos. La búsqueda predeterminada de 30 anuncios cuesta 0.5 créditos, y una búsqueda con `limit` 500 reserva 8.5 créditos. `advertisers` y `ad` cuestan 0.5 créditos cada uno. Solo se cobran las solicitudes completadas.

## Relacionado

* [Bibliotecas de anuncios comparadas](https://docs.querying.ai/es/engines/ad-libraries.md)
* [Biblioteca de anuncios de Meta](https://docs.querying.ai/es/engines/meta-ad-library.md)
* [Resumen de motores](https://docs.querying.ai/es/engines/overview.md)
* [Créditos y límites](https://docs.querying.ai/es/concepts/credits-and-limits.md)


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