> ## 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 do Google Ads Transparency

> Analise os anúncios dos concorrentes no Google Ads Transparency Center em JSON: liste os anúncios do Search, YouTube, Display, Play, Maps e Shopping que um anunciante veicula com há quantos dias cada um roda, e abra um anúncio para ver o texto, o vídeo e as impressões por país.

Leia o Google Ads Transparency Center como JSON pela API de tarefas assíncronas para ver quais anúncios do Google seus concorrentes veiculam. ADS é um mecanismo próprio: envie `taskType` `ADS` com `platform` `google_ads_transparency`, e `action` escolhe o que ler. A biblioteca cobre anúncios no Google Search, YouTube, Display, Google Play, Maps e Shopping em todos os países. Para escolher entre as bibliotecas de anúncios, veja [Bibliotecas de anúncios comparadas](https://docs.querying.ai/pt/engines/ad-libraries.md).

* `search` (padrão) lista os anúncios de um anunciante com `advertiserId`, de vários concorrentes de uma vez com `advertiserIds`, ou de todos os anunciantes cujos anúncios apontam para um site com `domain`. Cada anúncio traz o formato, o primeiro e o último dia de exibição e por quantos dias rodou, e a resposta termina com um `summary` dos anúncios retornados.
* `advertisers` encontra o `advertiserId` de um anunciante pelo nome.
* `ad` abre um anúncio: o texto, o vídeo e a página de destino e, onde a biblioteca os publica, as impressões por país e por superfície do Google.

Uma busca custa **0.5 crédito a cada 30 anúncios** que retorna. `advertisers` e `ad` custam 0.5 crédito cada.

## Requisição

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

Envie a tarefa e depois consulte `GET /v1/async/task/{id}` ou receba o webhook. Veja [Tarefas assíncronas](https://docs.querying.ai/pt/concepts/async-tasks.md).

## Analise os anúncios de um concorrente

Quatro requisições cobrem uma análise de concorrentes:

1. `advertisers` com o nome do concorrente retorna o `advertiserId` dele e os sites que a biblioteca sugere para o nome.
2. `search` com esse `advertiserId`, ou com o `domain` do concorrente, lista os anúncios dele. `activeDays` mostra quais anúncios rodam há mais tempo, `mediaType` e `publisherPlatforms` dividem os anúncios por criativo e superfície, e `summary` conta os formatos e os anúncios que começaram em cada semana.
3. `ad` com o `libraryId` e o `advertiserId` de um anúncio retorna o texto, o vídeo, os países que ele alcançou e, nos anúncios exibidos na UE, as impressões por país e superfície.
4. `search` com `advertiserIds` compara até 10 concorrentes em uma única requisição.

## Parâmetros

* `action`: `search` (padrão), `advertisers` ou `ad`.
* `query`: O nome de um anunciante, de 1 a 100 caracteres. `advertisers` o exige, e `search` e `ad` o recusam.
* `advertiserId`: O ID de um anunciante, como `AR16396071307843731457`. `search` precisa de `advertiserId`, `advertiserIds` ou `domain`, e `ad` exige `advertiserId`.
* `advertiserIds`: De 1 a 10 IDs de anunciante, como array ou texto separado por vírgulas. Envie `advertiserIds` ou `advertiserId` em uma mesma requisição.
* `domain`: Um domínio simples como `nike.com`. `search` lista os anúncios que apontam para ele, seja qual for o anunciante que os veicula. `domain` e os IDs de anunciante se excluem mutuamente.
* `libraryId`: O ID de criativo de um anúncio, como `CR07264436911983296513`. `ad` o exige.
* `country`: Onde os anúncios foram exibidos, como código de país de duas letras, ou `ALL` para todos os países (padrão). Um país por vez. `search` o lê.
* `publisherPlatforms`: Onde os anúncios rodaram: `search`, `youtube`, `maps`, `shopping` ou `play`. Um valor por vez.
* `mediaType`: `all` (padrão), `text`, `image` ou `video`.
* `startDate`, `endDate`: `YYYY-MM-DD`, enviados juntos. Mantém os anúncios exibidos pelo menos uma vez entre os dois dias.
* `limit`: De 1 a 500 anúncios em `search` (padrão 30), de 1 a 50 anunciantes em `advertisers` (padrão 30).
* `cursor`: O `nextCursor` de uma resposta anterior, para ler os anúncios seguintes.

`search` lê `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType`, `startDate`, `endDate`, `limit` e `cursor`. `advertisers` lê `query` e `limit`, e `ad` lê `advertiserId` e `libraryId`. Um campo que a biblioteca não consegue pesquisar, como `pageId`, `activeStatus` ou `sortBy`, ou um campo que a ação não lê, é recusado com `400 VALIDATION_ERROR`, e `details` indica o campo.

## Compare concorrentes

`advertiserIds` lista os anúncios de até 10 anunciantes em uma única requisição. O `summary` da resposta conta os anúncios de cada anunciante, então uma requisição mostra quem veicula mais anúncios.

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

## Ler mais anúncios

Uma página da biblioteca contém até 100 anúncios, então um `limit` acima de 100 lê várias páginas em uma única requisição. Uma resposta com mais anúncios para ler traz `nextCursor`. Envie-o como `cursor` com a mesma busca para receber os anúncios seguintes, de novo até `limit`. `nextCursor` é `null` quando a biblioteca não tem mais.

Um cursor só funciona com a busca que o retornou: um `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType` ou intervalo de datas diferente é recusado com `400 VALIDATION_ERROR`, enquanto `limit` pode mudar.

## Encontre um anunciante

`action` `advertisers` retorna os anunciantes cujos nomes correspondem a `query`, como a caixa de busca da biblioteca os sugere. Envie o `advertiserId` que você escolher para buscar os anúncios desse 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 tem `advertiserId`, `advertiserName`, `country` (onde o anunciante é registrado), `verified`, `adCountRange` (a faixa de anúncios do anunciante que a biblioteca informa, `min` e `max`) e `libraryUrl`, que abre o anunciante no Transparency Center. `adCount` é `null` porque a biblioteca informa uma faixa. `domains` lista os sites que a biblioteca sugere para o nome, que `search` aceita como `domain`. Um nome que nenhum anunciante tem termina com `advertisers` vazio. Uma busca de anunciantes aceita apenas `query` e `limit`, e custa 0.5 crédito.

## Resposta da busca

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

* A resposta repete `platform`, `action`, `country`, `advertiserId`, `advertiserIds` ou `domain`, e os filtros recebidos.
* `totalCountRange` é a estimativa da biblioteca para os anúncios correspondentes, como `min` e `max`. `totalCount` é `null`. `returnedCount` conta os anúncios em `ads`, `hasMore` é `true` quando a biblioteca tem mais, o que `nextCursor` lê, e `libraryUrl` abre a mesma busca no Transparency Center.
* Cada anúncio tem `position`, `libraryId`, `libraryUrl`, `advertiserId`, `advertiserName`, `format` (`TEXT`, `IMAGE` ou `VIDEO`), `width`, `height`, `images`, `videos`, `startDate`, `endDate`, `activeDays`, `isActive` e `landingDomain`.
* `startDate` e `endDate` são o primeiro e o último dia em que a biblioteca mostra o anúncio (dias em UTC). `activeDays` conta os dias de `startDate` a `endDate`, ambos incluídos, e é `null` quando a biblioteca não informa `startDate`. `isActive` é `true` para um anúncio exibido pela última vez hoje ou ontem, porque a biblioteca publica a última vez que um anúncio foi exibido e não se ele continua rodando.
* `landingDomain` é o host da página de destino do anúncio, em minúsculas e sem `www.`, e `null` quando a biblioteca não informa nenhum.
* Muitos anúncios de texto chegam como imagem: `images` traz um link para o anúncio como a biblioteca o desenha, e o texto está em `ad`. `title`, `body`, `ctaText` e `linkUrl` são `null` em uma busca e são preenchidos por `ad` quando a prévia do anúncio os tem. `impressions` é preenchido por `ad` nos anúncios exibidos na UE. `platforms`, `targeting`, `payer` e `utm` são `null`.
* `summary` conta os anúncios desta resposta: `ads`, `activeAds`, `advertisers` (os 10 com mais anúncios: `advertiserId`, `advertiserName`, `ads`), `formats`, `landingDomains` (os 10 com mais anúncios), `oldestStartDate`, `newestStartDate` e `medianActiveDays`. Também tem `launchesByWeek` (os anúncios que começaram em cada semana ISO, da semana mais antiga para a mais recente) e `longestRunning` (os 5 anúncios com mais `activeDays`). Uma busca com `limit` 500 resume 500 anúncios, e cada página que você lê com `cursor` traz o resumo dos próprios anúncios.
* Os links de imagem dos anúncios (`tpc.googlesyndication.com`) não são assinados e continuam abertos. Os links de prévia de `ad` são assinados e podem expirar.
* Uma busca sem anúncios correspondentes termina com `ads` vazio e um `summary` de `0` anúncios.

## O que a biblioteca guarda

* A biblioteca mostra anúncios de todos os países. Um anúncio permanece cerca de 12 meses após o último dia em que foi exibido.
* Os anúncios exibidos na UE trazem impressões: uma faixa para o anúncio, para cada país com o primeiro e o último dia de exibição, e para cada superfície do Google. Os anúncios exibidos em outros lugares trazem os países que o anúncio alcançou e o último dia de exibição. Para eles, `ad` lê o primeiro dia de exibição (e `activeDays`) da lista de anúncios do anunciante, o mesmo valor que `search` retorna, e deixa `startDate` e `activeDays` como `null` somente se o anúncio não estiver entre os primeiros 800 da lista do país que alcançou; `debug.dates` é `detail`, `search` ou `not-found`.

Para guardar o histórico de anúncios de um concorrente, busque os anúncios dele periodicamente, por exemplo todos os dias, e armazene-os.

## Abra um anúncio

`action` `ad` abre o anúncio com o `libraryId` e o `advertiserId` que você enviar, ambos obtidos em uma busca. Retorna o anúncio, o anunciante dele e a transparência que a biblioteca publica para ele.

```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` tem os campos de um anúncio de busca, mais o texto da prévia do anúncio: `title`, `body`, `ctaText`, `displayUrl`, `linkUrl`, `longTitle`, `channelName`, `address` e `merchant`, cada um quando o anúncio o tem, e `videos` (`url`, `previewUrl`). `previewKind` nomeia o tipo do anúncio: `text` (Search), `local` (Maps, com `address`), `display` (Display e YouTube) ou `shopping` (com `merchant`). `previewText` lista os textos da prévia, e `previewUrl` a abre.
* `reachedCountries` lista os países em que o anúncio foi exibido, como códigos ISO.
* `impressions` (`min`, `max`) é a faixa de impressões que a biblioteca publica para anúncios exibidos na UE. Fora da UE é `null`.
* `advertiser` tem `advertiserId`, `advertiserName` e `libraryUrl`.
* `transparency` traz `startDate`, `endDate` e `impressions` do anúncio, as `surfaces` dele (`surfaceId` e a faixa de impressões de cada superfície do Google; `platform` nomeia uma superfície apenas quando ela é conhecida: `SEARCH` e `MAPS`) e os `countries` dele, cada um com seus próprios `startDate`, `endDate`, `impressions` e `surfaces`. Para um anúncio exibido fora da UE, `transparency` lista os países com o último dia de exibição, e as datas e impressões que a biblioteca informa apenas para a UE são `null` ali (o `startDate` do próprio anúncio é lido da lista de anúncios).
* `variants` lista as renderizações do anúncio que a biblioteca guarda: `width`, `height`, `imageUrl` e `previewUrl`.
* `platforms` e `targeting` são `null`, porque a biblioteca não publica segmentação.
* Um `libraryId` para o qual a biblioteca não tem anúncio falha com `PAGE_UNAVAILABLE`.

## Preço

Uma busca reserva 0.5 crédito a cada 30 anúncios que o `limit` dela pede, e cobra 0.5 crédito a cada 30 anúncios que retorna, no mínimo 0.5 crédito. A busca padrão de 30 anúncios custa 0.5 crédito, e uma busca com `limit` 500 reserva 8.5 créditos. `advertisers` e `ad` custam 0.5 crédito cada. Apenas requisições concluídas são cobradas.

## Relacionado

* [Bibliotecas de anúncios comparadas](https://docs.querying.ai/pt/engines/ad-libraries.md)
* [Biblioteca de Anúncios da Meta](https://docs.querying.ai/pt/engines/meta-ad-library.md)
* [Visão geral dos motores](https://docs.querying.ai/pt/engines/overview.md)
* [Créditos e limites](https://docs.querying.ai/pt/concepts/credits-and-limits.md)


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