Saltar para o conteúdo principal
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.
  • 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

Envie a tarefa e depois consulte GET /v1/async/task/{id} ou receba o webhook. Veja Tarefas assíncronas.

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.

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

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