Saltar al contenido principal
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.
  • 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

Envía la tarea y consulta 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:
  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.

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

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