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.
search(por defecto) lista los anuncios de un anunciante conadvertiserId, de varios competidores a la vez conadvertiserIds, o de todos los anunciantes cuyos anuncios enlazan a un sitio web condomain. 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 unsummaryde los anuncios devueltos.advertisersencuentra eladvertiserIdde un anunciante por su nombre.adabre 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.
advertisers y ad cuestan 0.5 créditos cada uno.
Solicitud
GET /v1/async/task/{id} o recibe su webhook. Consulta Tareas asíncronas.
Analiza los anuncios de un competidor
Cuatro solicitudes cubren un análisis de la competencia:advertiserscon el nombre del competidor devuelve suadvertiserIdy los sitios web que la biblioteca sugiere para ese nombre.searchcon eseadvertiserId, o con eldomaindel competidor, lista sus anuncios.activeDaysmuestra qué anuncios llevan más tiempo activos,mediaTypeypublisherPlatformsdividen los anuncios por creativo y superficie, ysummarycuenta los formatos y los anuncios que empezaron cada semana.adcon ellibraryIdy eladvertiserIdde 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.searchconadvertiserIdscompara hasta 10 competidores en una sola solicitud.
Parámetros
action:search(por defecto),advertisersoad.query: El nombre de un anunciante, de 1 a 100 caracteres.advertiserslo requiere, ysearchyadlo rechazan.advertiserId: El ID de un anunciante, comoAR16396071307843731457.searchnecesitaadvertiserId,advertiserIdsodomain, yadrequiereadvertiserId.advertiserIds: De 1 a 10 IDs de anunciante, como array o texto separado por comas. EnvíaadvertiserIdsoadvertiserIden una misma solicitud.domain: Un dominio simple comonike.com.searchlista los anuncios que enlazan a él, sea cual sea el anunciante que los publica.domainy los IDs de anunciante se excluyen entre sí.libraryId: El ID de creativo de un anuncio, comoCR07264436911983296513.adlo requiere.country: Dónde se mostraron los anuncios, como código de país de dos letras, oALLpara todos los países (por defecto). Un país cada vez.searchlo lee.publisherPlatforms: Dónde se publicaron los anuncios:search,youtube,maps,shoppingoplay. Un valor cada vez.mediaType:all(por defecto),text,imageovideo.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 ensearch(por defecto 30), de 1 a 50 anunciantes enadvertisers(por defecto 30).cursor: ElnextCursorde 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.
Leer más anuncios
Una página de la biblioteca contiene hasta 100 anuncios, así que unlimit 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.
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
- La respuesta devuelve
platform,action,country,advertiserId,advertiserIdsodomain, y los filtros recibidos. totalCountRangees la estimación de la biblioteca de los anuncios coincidentes, comominymax.totalCountesnull.returnedCountcuenta los anuncios deads,hasMoreestruecuando la biblioteca tiene más, quenextCursorlee, ylibraryUrlabre la misma búsqueda en el Transparency Center.- Cada anuncio tiene
position,libraryId,libraryUrl,advertiserId,advertiserName,format(TEXT,IMAGEoVIDEO),width,height,images,videos,startDate,endDate,activeDays,isActiveylandingDomain. startDateyendDateson el primer y el último día en que la biblioteca muestra el anuncio (días en UTC).activeDayscuenta los días desdestartDatehastaendDate, contando ambos, y esnullcuando la biblioteca no dastartDate.isActiveestruepara 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.landingDomaines el host de la página de destino del anuncio, en minúsculas y sinwww., ynullcuando la biblioteca no da ninguno.- Muchos anuncios de texto llegan como imagen:
imagescontiene un enlace al anuncio tal como lo dibuja la biblioteca, y el texto está enad.title,body,ctaTextylinkUrlsonnullen una búsqueda y los rellenaadcuando la vista previa del anuncio los tiene.impressionslo rellenaaden los anuncios mostrados en la UE.platforms,targeting,payeryutmsonnull. summarycuenta 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,newestStartDateymedianActiveDays. También incluyelaunchesByWeek(los anuncios que empezaron en cada semana ISO, de la semana más antigua a la más reciente) ylongestRunning(los 5 anuncios con másactiveDays). Una búsqueda conlimit500 resume 500 anuncios, y cada página que lees concursorincluye 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 deadestán firmados y pueden caducar. - Una búsqueda sin anuncios coincidentes se completa con
adsvacío y unsummaryde0anuncios.
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,
adlee el primer día de emisión (yactiveDays) de la lista de anuncios del anunciante, el mismo valor que devuelvesearch, y dejastartDateyactiveDaysennullsolo si el anuncio no está entre los primeros 800 anuncios de la lista para el país que alcanzó;debug.datesesdetail,searchonot-found.
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.
adtiene 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,addressymerchant, cada uno cuando el anuncio lo tiene, yvideos(url,previewUrl).previewKindindica el tipo de anuncio:text(Search),local(Maps, conaddress),display(Display y YouTube) oshopping(conmerchant).previewTextlista los textos de la vista previa, ypreviewUrlla abre.reachedCountrieslista 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 esnull.advertisertieneadvertiserId,advertiserNameylibraryUrl.transparencyincluyestartDate,endDateeimpressionsdel anuncio, sussurfaces(surfaceIdy el rango de impresiones de cada superficie de Google;platformnombra una superficie solo cuando se conoce:SEARCHyMAPS) y suscountries, cada uno con sus propiosstartDate,endDate,impressionsysurfaces. En un anuncio mostrado fuera de la UE,transparencylista los países con su último día de emisión, y las fechas e impresiones que la biblioteca da solo para la UE sonnullallí (elstartDatepropio del anuncio se lee de la lista de anuncios).variantslista las versiones renderizadas del anuncio que conserva la biblioteca:width,height,imageUrlypreviewUrl.platformsytargetingsonnull, porque la biblioteca no publica la segmentación.- Un
libraryIdpara el que la biblioteca no tiene ningún anuncio falla conPAGE_UNAVAILABLE.
Precio
Una búsqueda reserva 0.5 créditos por cada 30 anuncios que pide sulimit, 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.