taskType ADS con platform linkedin_ad_library, y action elige qué leer. Para elegir entre las bibliotecas de anuncios, consulta Bibliotecas de anuncios comparadas.
search(por defecto) lista anuncios por una palabra clave enquery, por el nombre de un anunciante enadvertiserName, por quién pagó enpayer, o por una combinación. Cada anuncio incluye su anunciante, formato, título, texto y contenido multimedia, y la respuesta termina con unsummaryde los anuncios devueltos.adabre un anuncio: el anunciante, quién pagó, la página de destino y, donde la biblioteca lo publica, las fechas de emisión, las impresiones, los países que alcanzó y su segmentación.
action advertisers se rechaza con 400 VALIDATION_ERROR. Encuentra a un competidor con advertiserName en una búsqueda.
Una búsqueda cuesta 0.5 créditos por cada 30 anuncios que devuelve. ad cuesta 0.5 créditos.
Solicitud
GET /v1/async/task/{id} o recibe su webhook. Consulta Tareas asíncronas. La biblioteca limita la velocidad de lectura, así que una búsqueda de 120 anuncios tarda unos treinta segundos.
Analiza los anuncios de un competidor
Tres solicitudes cubren un análisis de la competencia:searchcon el nombre del competidor enadvertiserNamelista sus anuncios.advertiserNamecoincide con parte de un nombre, así que revisaadvertiserNameen cada anuncio. Añadequerypara acotar los anuncios a un tema, ysortByoldestpara empezar por los anuncios más antiguos.adcon ellibraryIdde un anuncio devuelve quién pagó, la página de destino y, en los anuncios mostrados en la UE, las fechas de emisión, las impresiones y la segmentación.searchconpayerlista los anuncios que pagó una agencia o empresa, sea cual sea la página que los publica.
Parámetros
action:search(por defecto) oad.query: Una palabra clave en el texto del anuncio.searchnecesitaquery,advertiserNameopayer.advertiserName: Un nombre, que coincide con parte del nombre del anunciante, comosamsung.payer: El nombre de quien pagó el anuncio, que coincide con parte del nombre, comoStarcom.libraryId: El ID numérico de un anuncio, como1638962914.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).startDate,endDate:YYYY-MM-DD, enviados juntos, dentro del último año. Conserva los anuncios mostrados entre los dos días.sortBy:newest(por defecto) ooldest.limit: De 1 a 120 anuncios. Por defecto 30.cursor: ElnextCursorde una respuesta anterior, para leer los anuncios siguientes.
search lee todos los campos anteriores excepto libraryId, y ad lee solo libraryId. Un filtro de la Biblioteca de anuncios de Meta (pageId, pageIds, activeStatus, searchType, adType, mediaType, publisherPlatforms o contentLanguages), un valor que la biblioteca no puede buscar o un campo que la acción no lee se rechaza con 400 VALIDATION_ERROR, y details indica el campo.
Leer más anuncios
Una respuesta con más anuncios por leer incluyenextCursor. 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 query, advertiserName, payer, country, rango de fechas o sortBy distinto se rechaza con 400 VALIDATION_ERROR, mientras que limit puede cambiar.
Respuesta de búsqueda
- La respuesta devuelve
platform,action,country,query,advertiserName,payer,sortByy las fechas recibidas.returnedCountcuenta los anuncios deads,hasMoreestruecuando la biblioteca tiene más, quenextCursorlee, ylibraryUrlabre la misma búsqueda en la Biblioteca de anuncios.totalCountesnull, porque la biblioteca no da un recuento. - Cada anuncio es una tarjeta:
position,libraryId,libraryUrl,advertiserName,advertiserLogoUrl,creativeType(comoSPONSORED_STATUS_UPDATEoSPONSORED_VIDEO),format,title,body,imagesyvideos(el póster del vídeo enpreviewUrl), yplatforms(LINKEDIN).formatesIMAGE,VIDEO,CAROUSEL,DOCUMENT,ARTICLE,MESSAGE,JOB,SPOTLIGHToFOLLOW_COMPANY. - Los anuncios de mensaje y los anuncios Thought Leader incluyen
member, el remitente del mensaje o el miembro cuya publicación promueve el anuncio, connameyurl;adlo devuelve con la misma forma. En los demás anuncios,memberesnull. - Una tarjeta incluye los primeros 120 caracteres del texto, y
bodyTruncatedestruecuando el texto es más largo.addevuelve el texto completo. advertiserId,payer,startDate,endDate,activeDays,linkUrl,landingDomain,impressions,targeting,ctaTextyutmsonnullen una tarjeta.adlos rellena cuando la biblioteca los tiene.isActiveesnull, porque la biblioteca no indica si un anuncio sigue en emisión.summarycuenta los anuncios de esta respuesta:ads,advertisers(los 10 con más anuncios:advertiserName,ads),formatsyplatforms. Sus campos de fecha (oldestStartDate,newestStartDate,medianActiveDays,launchesByWeekylongestRunning) quedan vacíos o ennull, porque las tarjetas no incluyen fechas.- Una búsqueda sin anuncios coincidentes se completa con
adsvacío y unsummaryde0anuncios.
Qué conserva la biblioteca
- El creativo, el anunciante y el pagador de cada anuncio están disponibles para todos los países.
- Las fechas de emisión, el rango de impresiones, el porcentaje de impresiones por país y la segmentación solo están disponibles para los anuncios mostrados en la UE.
- La biblioteca conserva los anuncios durante unos 12 meses, y su filtro de fechas solo acepta el último año.
Abrir un anuncio
action ad abre el anuncio con el libraryId que envíes, obtenido de una búsqueda o de la dirección de la Biblioteca de anuncios /ad-library/detail/<libraryId>.
adtiene los campos de una tarjeta de búsqueda con el texto completo, másadvertiserId,advertiserUrl,advertiserType(companyoperson),payer(quién pagó el anuncio),linkUrl,landingDomain,ctaText,startDate,endDate,activeDays,impressions,targetingyreachedCountries.impressionses el rango que publica la biblioteca (min,max).targetinglista los idiomas y ubicaciones que el anunciante incluyó o excluyó (language,location) y los parámetros de segmentación (parameters:parameter,targeted,excluded). Las fechas,impressions,targetingyreachedCountriessonnullen un anuncio que no se mostró en la UE, como el anuncio de Adobe1698237666. El pagador y el anunciante aparecen en todos los anuncios.videoslista cada vídeo conurl(el archivo con la tasa de bits más alta),files(cada mp4:url,type,bitrate) ypreviewUrl. Un anuncio de carrusel añadecards(title,imageUrl) y un anuncio de documento añadedocument(su título, número de páginas y portadas de las páginas).advertiseres la página que hay detrás del anuncio:advertiserId,advertiserName,url,typeylogoUrl.transparencyesnullen un anuncio no mostrado en la UE. En un anuncio mostrado en la UE contieneimpressions,impressionsText(el texto de la biblioteca, como50k-100k) yreachByCountry, el porcentaje de las impresiones en cada país (country,countryCode,share,shareText), también fuera de la UE.variantslista las otras versiones del anuncio cuando la biblioteca muestra más de una, y esnullen caso contrario.- Las URL del contenido multimedia de los creativos siguen abiertas durante años. Las URL de las tarjetas de un carrusel caducan tras una semana aproximadamente, y los logotipos de los anunciantes tras unas dos semanas y media. Guarda los archivos que necesites.
- 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 120 reserva 2 créditos. ad cuesta 0.5 créditos. Solo se cobran las solicitudes completadas.