Saltar al contenido principal
Busca en la Biblioteca de anuncios de Meta y recibe JSON mediante la API de tareas asíncronas. Envía 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

Envía la tarea y luego consulta 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), o advertisers, que busca anunciantes por su nombre.
  • query: una palabra clave. Busca las palabras del texto de un anuncio en cualquier orden. Obligatorio si no hay pageId.
  • pageId: el ID numérico de la página de Facebook de un anunciante, como 266556540473351. Reúne los anuncios de ese anunciante y, con query, busca entre ellos.
  • country: dónde circularon los anuncios, como código de país de dos letras, o ALL para todos los países. Por defecto, US.
  • activeStatus: active (por defecto), inactive o all.
  • limit: de 1 a 500 anuncios. Por defecto, 30.
  • cursor: el nextCursor de una respuesta anterior, para leer los anuncios que siguen.
  • searchType: keyword_unordered (por defecto) o keyword_exact_phrase.
  • adType: all (por defecto), political_and_issue_ads, housing_ads, employment_ads o financial_products_and_services_ads.
  • mediaType: all (por defecto), image, meme, image_and_meme, video o none.
  • publisherPlatforms: uno o más de facebook, instagram, audience_network, messenger, whatsapp y threads, 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) o most_recent. impressions_low_to_high requiere adType political_and_issue_ads, los únicos anuncios que la biblioteca ordena así.
Un valor que la biblioteca no puede buscar se rechaza con 400 VALIDATION_ERROR, y details indica el campo.

Leer más anuncios

Una respuesta con más anuncios por leer trae nextCursor. 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.
Un cursor solo sirve para la búsqueda que lo devolvió: si cambian 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.
Cada anunciante tiene 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, query o pageId, activeStatus y los filtros recibidos.
  • totalCount es el recuento de anuncios coincidentes de la propia biblioteca, que lo redondea en las búsquedas grandes. returnedCount cuenta los anuncios de ads, hasMore es true cuando la biblioteca tiene más, que nextCursor permite leer, y libraryUrl abre la misma búsqueda en la Biblioteca de anuncios.
  • Cada anuncio tiene position, libraryId, libraryUrl, isActive, startDate y endDate (días en UTC), platforms, versions (cuántos anuncios usan este contenido y este texto), format (IMAGE, VIDEO, CAROUSEL, DCO, DPA, MULTI_IMAGES y otros), body, title, caption, linkUrl, linkDescription, ctaText, ctaType y categories (las categorías del anuncio según la biblioteca, como POLITICAL o EMPLOYMENT).
  • El anunciante es pageId, pageName, pageProfileUrl, pageProfilePictureUrl, pageLikeCount y pageCategories. Los anuncios sobre temas sociales, elecciones o política añaden byline, quién pagó el anuncio, y disclaimerLabel, y una colaboración pagada añade la página del socio en brandedContent.
  • El contenido multimedia es images (url, resizedUrl), videos (hdUrl, sdUrl, previewImageUrl) y cards, las tarjetas de un anuncio por secuencia o de catálogo, cada una con su title, body, linkUrl, caption, linkDescription, ctaText, ctaType, imageUrl, resizedImageUrl y video. Los demás textos, enlaces, imágenes y vídeos de un anuncio dinámico están en extraTexts, extraLinks, extraImages y extraVideos.
  • 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, impressions y reach solo 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 ads vacío y totalCount 0.

Precio

Una búsqueda retiene al empezar 0.5 créditos por cada 30 anuncios que pide limit, 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.

Relacionado