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 comadvertiserId, de vários concorrentes de uma vez comadvertiserIds, ou de todos os anunciantes cujos anúncios apontam para um site comdomain. 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 umsummarydos anúncios retornados.advertisersencontra oadvertiserIdde um anunciante pelo nome.adabre 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.
advertisers e ad custam 0.5 crédito cada.
Requisição
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:advertiserscom o nome do concorrente retorna oadvertiserIddele e os sites que a biblioteca sugere para o nome.searchcom esseadvertiserId, ou com odomaindo concorrente, lista os anúncios dele.activeDaysmostra quais anúncios rodam há mais tempo,mediaTypeepublisherPlatformsdividem os anúncios por criativo e superfície, esummaryconta os formatos e os anúncios que começaram em cada semana.adcom olibraryIde oadvertiserIdde 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.searchcomadvertiserIdscompara até 10 concorrentes em uma única requisição.
Parâmetros
action:search(padrão),advertisersouad.query: O nome de um anunciante, de 1 a 100 caracteres.advertiserso exige, esearcheado recusam.advertiserId: O ID de um anunciante, comoAR16396071307843731457.searchprecisa deadvertiserId,advertiserIdsoudomain, eadexigeadvertiserId.advertiserIds: De 1 a 10 IDs de anunciante, como array ou texto separado por vírgulas. EnvieadvertiserIdsouadvertiserIdem uma mesma requisição.domain: Um domínio simples comonike.com.searchlista os anúncios que apontam para ele, seja qual for o anunciante que os veicula.domaine os IDs de anunciante se excluem mutuamente.libraryId: O ID de criativo de um anúncio, comoCR07264436911983296513.ado exige.country: Onde os anúncios foram exibidos, como código de país de duas letras, ouALLpara todos os países (padrão). Um país por vez.searcho lê.publisherPlatforms: Onde os anúncios rodaram:search,youtube,maps,shoppingouplay. Um valor por vez.mediaType:all(padrão),text,imageouvideo.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 emsearch(padrão 30), de 1 a 50 anunciantes emadvertisers(padrão 30).cursor: OnextCursorde 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 umlimit 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.
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,advertiserIdsoudomain, e os filtros recebidos. totalCountRangeé a estimativa da biblioteca para os anúncios correspondentes, comominemax.totalCounténull.returnedCountconta os anúncios emads,hasMoreétruequando a biblioteca tem mais, o quenextCursorlê, elibraryUrlabre a mesma busca no Transparency Center.- Cada anúncio tem
position,libraryId,libraryUrl,advertiserId,advertiserName,format(TEXT,IMAGEouVIDEO),width,height,images,videos,startDate,endDate,activeDays,isActiveelandingDomain. startDateeendDatesão o primeiro e o último dia em que a biblioteca mostra o anúncio (dias em UTC).activeDaysconta os dias destartDateaendDate, ambos incluídos, e énullquando a biblioteca não informastartDate.isActiveétruepara 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 semwww., enullquando a biblioteca não informa nenhum.- Muitos anúncios de texto chegam como imagem:
imagestraz um link para o anúncio como a biblioteca o desenha, e o texto está emad.title,body,ctaTextelinkUrlsãonullem uma busca e são preenchidos poradquando a prévia do anúncio os tem.impressionsé preenchido poradnos anúncios exibidos na UE.platforms,targeting,payereutmsãonull. summaryconta 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,newestStartDateemedianActiveDays. Também temlaunchesByWeek(os anúncios que começaram em cada semana ISO, da semana mais antiga para a mais recente) elongestRunning(os 5 anúncios com maisactiveDays). Uma busca comlimit500 resume 500 anúncios, e cada página que você lê comcursortraz 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 deadsão assinados e podem expirar. - Uma busca sem anúncios correspondentes termina com
adsvazio e umsummaryde0anú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,
adlê o primeiro dia de exibição (eactiveDays) da lista de anúncios do anunciante, o mesmo valor quesearchretorna, e deixastartDateeactiveDayscomonullsomente se o anúncio não estiver entre os primeiros 800 da lista do país que alcançou;debug.datesédetail,searchounot-found.
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.
adtem os campos de um anúncio de busca, mais o texto da prévia do anúncio:title,body,ctaText,displayUrl,linkUrl,longTitle,channelName,addressemerchant, cada um quando o anúncio o tem, evideos(url,previewUrl).previewKindnomeia o tipo do anúncio:text(Search),local(Maps, comaddress),display(Display e YouTube) oushopping(commerchant).previewTextlista os textos da prévia, epreviewUrla abre.reachedCountrieslista 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.advertisertemadvertiserId,advertiserNameelibraryUrl.transparencytrazstartDate,endDateeimpressionsdo anúncio, assurfacesdele (surfaceIde a faixa de impressões de cada superfície do Google;platformnomeia uma superfície apenas quando ela é conhecida:SEARCHeMAPS) e oscountriesdele, cada um com seus própriosstartDate,endDate,impressionsesurfaces. Para um anúncio exibido fora da UE,transparencylista 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ãonullali (ostartDatedo próprio anúncio é lido da lista de anúncios).variantslista as renderizações do anúncio que a biblioteca guarda:width,height,imageUrlepreviewUrl.platformsetargetingsãonull, porque a biblioteca não publica segmentação.- Um
libraryIdpara o qual a biblioteca não tem anúncio falha comPAGE_UNAVAILABLE.
Preço
Uma busca reserva 0.5 crédito a cada 30 anúncios que olimit 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.