taskType ADS con platform meta_ad_library y una palabra clave en query o el ID de la página de Facebook de un anunciante en pageId. Una búsqueda cuesta 0.5 créditos por cada 30 anuncios que devuelve. Para encontrar el ID de página de un anunciante por su nombre, envía action advertisers.
Solicitud
GET /v1/async/task/{id} o recibe su webhook. Consulta Tareas asíncronas. Una búsqueda de 30 anuncios suele completarse en unos segundos, y una de 500 anuncios en alrededor de un minuto.
Parámetros
action:search(por defecto), oadvertisers, que busca anunciantes por su nombre.query: una palabra clave. Busca las palabras del texto de un anuncio en cualquier orden. Obligatorio si no haypageId.pageId: el ID numérico de la página de Facebook de un anunciante, como266556540473351. Reúne los anuncios de ese anunciante y, conquery, busca entre ellos.country: dónde circularon los anuncios, como código de país de dos letras, oALLpara todos los países. Por defecto,US.activeStatus:active(por defecto),inactiveoall.limit: de 1 a 500 anuncios. Por defecto, 30.cursor: elnextCursorde una respuesta anterior, para leer los anuncios que siguen.searchType:keyword_unordered(por defecto) okeyword_exact_phrase.adType:all(por defecto),political_and_issue_ads,housing_ads,employment_adsofinancial_products_and_services_ads.mediaType:all(por defecto),image,meme,image_and_meme,videoonone.publisherPlatforms: uno o más defacebook,instagram,audience_network,messenger,whatsappythreads, como array o como texto separado por comas.contentLanguages: uno o más códigos de idioma de dos letras.startDate,endDate:YYYY-MM-DD. Conserva los anuncios mostrados entre las dos fechas.sortBy:impressions_high_to_low(por defecto) omost_recent.impressions_low_to_highrequiereadTypepolitical_and_issue_ads, los únicos anuncios que la biblioteca ordena así.
400 VALIDATION_ERROR, y details indica el campo.
Leer más anuncios
Una respuesta con más anuncios por leer traenextCursor. Envíalo como cursor con la misma búsqueda para recibir los anuncios siguientes, de nuevo hasta limit. Las posiciones siguen desde la respuesta anterior, y nextCursor es null cuando la biblioteca no tiene más.
query, pageId, country, activeStatus o un filtro, se rechaza con 400 VALIDATION_ERROR, mientras que limit puede cambiar. El cursor crece con los anuncios leídos antes, hasta unos 14 KB tras mil anuncios, así que guárdalo como texto sin límite de longitud. La biblioteca a veces lista un anuncio dos veces, por lo que un anuncio puede volver en una respuesta posterior; libraryId distingue las repeticiones.
Encontrar un anunciante
action advertisers devuelve las páginas de Facebook de los anunciantes cuyo nombre coincide con query, como las sugiere el buscador de la biblioteca. Envía el pageId que elijas para buscar los anuncios de ese anunciante.
position, pageId, name, category, likeCount, verified (la insignia azul de Meta), country (el país de la página cuando Meta lo indica, como la página británica de una marca global), pageAlias, profileUrl, pictureUrl, instagramUsername, instagramFollowerCount, instagramVerified y libraryUrl, que abre sus anuncios en la Biblioteca de anuncios. keywords enumera las búsquedas que la biblioteca sugiere para el nombre. La biblioteca busca el nombre tal como lo escribe la página: Shokz encuentra las páginas de Shokz y 샥즈 no encuentra ninguna. Un nombre que ninguna página lleva termina con advertisers vacío. Una búsqueda de anunciantes solo admite query y country, y cuesta 0.5 créditos.
Ejemplo de respuesta
Campos del resultado
- La respuesta repite
platform,action,country,queryopageId,activeStatusy los filtros recibidos. totalCountes el recuento de anuncios coincidentes de la propia biblioteca, que lo redondea en las búsquedas grandes.returnedCountcuenta los anuncios deads,hasMoreestruecuando la biblioteca tiene más, quenextCursorpermite leer, ylibraryUrlabre la misma búsqueda en la Biblioteca de anuncios.- Cada anuncio tiene
position,libraryId,libraryUrl,isActive,startDateyendDate(días en UTC),platforms,versions(cuántos anuncios usan este contenido y este texto),format(IMAGE,VIDEO,CAROUSEL,DCO,DPA,MULTI_IMAGESy otros),body,title,caption,linkUrl,linkDescription,ctaText,ctaTypeycategories(las categorías del anuncio según la biblioteca, comoPOLITICALoEMPLOYMENT). - El anunciante es
pageId,pageName,pageProfileUrl,pageProfilePictureUrl,pageLikeCountypageCategories. Los anuncios sobre temas sociales, elecciones o política añadenbyline, quién pagó el anuncio, ydisclaimerLabel, y una colaboración pagada añade la página del socio enbrandedContent. - El contenido multimedia es
images(url,resizedUrl),videos(hdUrl,sdUrl,previewImageUrl) ycards, las tarjetas de un anuncio por secuencia o de catálogo, cada una con sutitle,body,linkUrl,caption,linkDescription,ctaText,ctaType,imageUrl,resizedImageUrlyvideo. Los demás textos, enlaces, imágenes y vídeos de un anuncio dinámico están enextraTexts,extraLinks,extraImagesyextraVideos. - Las URL del contenido multimedia son enlaces de la CDN de Meta que caducan a los pocos días. Guarda los archivos que necesites.
- Los anuncios de catálogo (
DPA,DCO) conservan en su texto los marcadores de la biblioteca, como{{product.name}}. spend,currency,impressionsyreachsolo aparecen donde la biblioteca los publica: anuncios sobre temas sociales, elecciones o política, y anuncios mostrados en la UE.- Una búsqueda sin anuncios coincidentes se completa con
adsvacío ytotalCount0.
Precio
Una búsqueda retiene al empezar 0.5 créditos por cada 30 anuncios que pidelimit, y cuesta 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 retiene 8.5 créditos. Una búsqueda de anunciantes cuesta 0.5 créditos. Solo se cobran las solicitudes completadas.