Cómo Usar la API de la Biblioteca de Anuncios de Facebook (Meta)

La API de la Biblioteca de Anuncios de Facebook/Meta, a la que nos referimos como la API de la Biblioteca de Anuncios de Facebook, es una interfaz disponible públicamente que da a los desarrolladores acceso a los anuncios publicados en Facebook, Instagram y otras plataformas propiedad de Meta (por ejemplo, WhatsApp y Threads). A través de esta API, puedes buscar anuncios por palabra clave, ID de página, país o tipo de anuncio, y recuperar metadatos como creativos de anuncios, rangos de gasto, impresiones, plataformas de publicación y muchos más.

Esta API es particularmente útil para la investigación de transparencia, auditorías de marketing, análisis competitivo, análisis de creativos de anuncios o la creación de herramientas en torno a los datos de anuncios en redes sociales. Ya sea que quieras monitorear anuncios activos, estudiar anuncios políticos o de temas sociales (anuncios SIEP) o analizar estrategias de marketing, la API de la Biblioteca de Anuncios de Facebook ofrece una potente puerta de entrada a los datos de anuncios.

¿Por qué usar la API de la Biblioteca de Anuncios de Facebook y qué te permite hacer?

Algunas de las capacidades clave de la API de la Biblioteca de Anuncios de Facebook:

1. Buscar por palabras clave, ID de página, país, tipo de anuncio — puedes restringir los anuncios por lo que contienen, quién los colocó, dónde se publican y qué tipo de campaña son.
2. Filtrar por estado: activos/inactivos, rangos de gasto, impresiones — útil cuando solo quieres anuncios actualmente en ejecución o aquellos por encima/debajo de ciertos umbrales de gasto.
3. Recuperar metadatos de anuncios — incluyendo campos como page_name, ad_snapshot_url, spend, impressions, publisher_platforms (Facebook/Instagram), y más.
4. Soporte para cobertura de datos a largo plazo y amplia — por ejemplo, a nivel mundial para anuncios SIEP, y para muchas regiones para anuncios generales (sujeto a las políticas regionales de Meta a partir de 2025).
5. Acceso gratuito a datos públicos — sin costo inicial para recuperar datos de anuncios públicos, siempre que tengas la configuración de acceso adecuada.

En resumen, la API ofrece una forma estructurada y programable de explorar y recopilar datos de anuncios a escala.

Guía Paso a Paso: Cómo empezar con la API de la Biblioteca de Anuncios de Facebook

Paso 1: Verifica tu cuenta e identidad de Facebook/Meta

• Inicia sesión/crea tu cuenta de Facebook (personal o de empresa).
• Asegúrate de que tu cuenta esté verificada (Meta a veces requiere verificación de identidad para el acceso a la API). (Verificación de cuenta)
• Este paso es importante, especialmente si planeas solicitar acceso a los datos de la biblioteca de anuncios a través de una aplicación.

Paso 2: Registra una aplicación de desarrollador de Meta

• Visita Meta para Desarrolladores → “Empezar” e inicia sesión en la plataforma. (Haz clic aquí)

• Crea una nueva aplicación: elige “Otro” o un tipo genérico si no estás anunciando.

• Selecciona que quieres acceso a las API de Marketing / Biblioteca de Anuncios.

• Inicialmente, la aplicación estará en modo de Desarrollo, lo cual es suficiente para pruebas básicas y uso a pequeña escala.

Paso 3: Genera un token de acceso

• Usa el Explorador de la API de Graph o las herramientas de Meta para generar un token de acceso de usuario.
• Asegúrate de que el token tenga los permisos necesarios (por ejemplo, ads_read, posiblemente ads_archive u otros según los requisitos de Meta). (Facebook para Desarrolladores)

Nota: los tokens de acceso caducan; es posible que necesites extenderlos o generar tokens de larga duración dependiendo de tu uso.

Paso 4: Realiza tu primera llamada a la API

Puedes consultar el endpoint /ads_archive (la raíz de la API de la Biblioteca de Anuncios). Usa la última versión de la API (por ejemplo, v23.0 o más reciente). (Facebook para Desarrolladores)

Ejemplo: usando curl

curl -G \
  -d "search_terms=skincare" \
  -d "ad_reached_countries=['US']" \
  -d "ad_active_status=ACTIVE" \
  -d "fields=page_name,ad_snapshot_url,spend,impressions,publisher_platforms" \
  -d "access_token=YOUR_ACCESS_TOKEN" \
  "https://graph.facebook.com/v23.0/ads_archive"

Ejemplo: usando JavaScript (fetch)

const response = await fetch(
  `https://graph.facebook.com/v23.0/ads_archive?` +
  `search_terms=skincare&ad_reached_countries=['US']&ad_active_status=ACTIVE` +
  `&fields=page_name,spend,impressions,publisher_platforms` +
  `&access_token=YOUR_ACCESS_TOKEN`
);
const data = await response.json();
console.log(data);

La respuesta JSON incluirá una matriz de objetos de anuncios, cada uno con metadatos como page_name, ad_snapshot_url, rangos de gasto, rango de impresiones, plataformas de publicación y, potencialmente, más campos.

Paso 5: Manejo de paginación y resultados grandes

Dado que la Biblioteca de Anuncios puede devolver muchos resultados, la API utiliza paginación. Prepárate para iterar a través de las páginas subsiguientes — examina la respuesta en busca de tokens de paging o cursor e itera en consecuencia. Los desarrolladores a menudo construyen bucles en el código para agregar grandes conjuntos de resultados.

Paso 6: Casos de Uso — ¿Qué puedes hacer con estos datos?

Aquí tienes casos de uso comunes:

1. Análisis competitivo — recupera anuncios de la Página de Facebook de un competidor (a través del ID de página) para estudiar sus creativos, estimaciones de gasto o alcance de segmentación.
2. Monitoreo e investigación de tendencias — rastrea qué tipos de anuncios están activos por palabra clave, región, tipo de medio o tipo de anuncio (por ejemplo, político, vivienda, temas sociales).
3. Paneles de inteligencia de marketing — agrega datos (rangos de gasto, impresiones, frecuencia de anuncios) y visualiza a lo largo del tiempo o entre regiones.
4. Análisis / inspiración de creativos de anuncios — obtén y archiva creativos de anuncios (URL de imágenes/videos) para inspiración de productos o auditorías de cumplimiento.
5. Investigación académica / de transparencia — usa datos de anuncios para estudios sobre publicidad política, campañas de temas sociales o tendencias del mercado.

Estos casos de uso resaltan el valor de tener acceso estructurado y programático a los datos de anuncios.

Probando la API de la Biblioteca de Anuncios de Facebook con Apidog

Usa Apidog como campo de pruebas para la API de la Biblioteca de Anuncios de Facebook. Aquí te explicamos cómo empezar a probar tus API en Apidog:

1. En Apidog, crea un nuevo endpoint de API: establece el método en GET, la URL en https://graph.facebook.com/v23.0/ads_archive.

2. Bajo los parámetros de consulta, añade parámetros como search_terms, ad_reached_countries, fields y access_token.

3. Pulsa “Enviar” — Apidog obtendrá los datos y te mostrará la respuesta JSON de forma estructurada.

4. Puedes experimentar con múltiples combinaciones de parámetros, probar la paginación e incluso guardar respuestas de ejemplo para documentación o análisis.

Este enfoque es especialmente útil para una exploración rápida de datos de anuncios, probar consultas de búsqueda y construir integraciones sin escribir código completo.

Preguntas Frecuentes

P1. ¿Necesito una cuenta publicitaria especial o una cuenta de empresa para usar la API de la Biblioteca de Anuncios de Facebook?
No, una cuenta Meta verificada suele ser suficiente. Sin embargo, debes registrar una aplicación de desarrollador de Meta y obtener un token de acceso con los permisos adecuados (por ejemplo, ads_read, ads_archive). Algunos usuarios necesitan completar la verificación de identidad para acceso completo.

P2. ¿Puedo obtener datos de cualquier anuncio (no solo anuncios políticos o de temas sociales)?
Sí, la API soporta anuncios generales (no solo SIEP). Puedes usar ad_type=all (o omitir el filtro) dependiendo de la región y la disponibilidad de anuncios.

P3. ¿Cuántos anuncios puedo recuperar en una sola solicitud?
Por defecto, la API devuelve un número limitado de anuncios por solicitud (paginación). Para recuperar más, necesitas iterar a través de las páginas usando el cursor de paginación proporcionado en la respuesta.

P4. ¿Puedo acceder a los creativos de anuncios (imágenes, videos) a través de la API?
Obtienes ad_snapshot_url o campos similares que enlazan a la vista previa del creativo del anuncio. Sin embargo, Meta no siempre proporciona archivos multimedia directos; obtener imágenes o videos reales podría requerir pasos adicionales.

P5. ¿Hay alguna forma de automatizar la recuperación de datos y evitar problemas de caducidad del token?
Sí, puedes generar tokens de larga duración en las herramientas de desarrollador de Meta o configurar un sistema backend que refresque los tokens periódicamente. Para la recuperación de datos a gran escala, la combinación de gestión de tokens con bucles de paginación es común. Siempre almacena los tokens de forma segura.

Conclusión

La API de la Biblioteca de Anuncios de Facebook (Meta) proporciona una potente puerta de entrada estructurada a los datos de anuncios, lo que permite a desarrolladores, especialistas en marketing, investigadores y analistas buscar, recopilar y analizar programáticamente campañas publicitarias en las plataformas de Meta. Usándola, puedes construir paneles, realizar análisis competitivos, llevar a cabo investigaciones de transparencia o agregar creativos de anuncios a escala.

Al configurar una aplicación de desarrollador de Meta, obtener un token de acceso adecuado y realizar solicitudes al endpoint /ads_archive —opcionalmente probando a través de herramientas como Apidog— puedes desbloquear una gran cantidad de datos de la biblioteca de anuncios. Si bien existen limitaciones (permisos, límites de tasa, paginación, recuperación de medios), los beneficios a menudo superan el trabajo.

Para cualquiera que necesite datos de anuncios públicos de Facebook/Meta, la API de la Biblioteca de Anuncios es una opción valiosa, oficial y flexible.