Documentos
Ctrl+K Buscar Alt+[Alt+] Guías
Obtener clave API

API · Biblioteca de anuncios

API de la biblioteca de anuncios de Meta (/api/v1/adlibrary)

Esto complementa el Referencia de la API. Usar GET /api/v1/adlibrary (o el alias heredado GET /api/adlibrary) con tu Clave API para buscar anuncios de Meta (Facebook / Instagram) de forma programada.

Nota sobre la ruta: /api/v1/adlibrary es canónico; /api/adlibrary es un contador compatible alias. Los siguientes ejemplos utilizan /api/v1/... para llamadas programáticas. Marcas registradas mediante una clave API (GET /api/v1/marcas) y pestañas de detalles de la marca en la sesión se recogen en Marcas y seguimiento de marcas.

Herramienta MCP (anuncios de Meta)

  • buscar_anuncios_en_Facebook — el mismo flujo subyacente que GET /api/v1/adlibrary (palabra clave, país, página, ordenar).
  • encontrar_productos_ganadores — Vista de productos ganadores basada en la biblioteca de anuncios (aplica filtros de puntuación ganadora y de página de producto para la búsqueda de productos).
  • paquete_de_inspiración_creativa — Una selección de anuncios respaldada por la biblioteca de anuncios, con ganchos, páginas de destino y combinación de medios.
  • resumen_de_la_competencia — Resumen rápido de la competencia a partir de AdLibrary y de las señales de Store/Tracker.
  • scan_ad — Escáner de ID de anuncios y URL con hook + evaluación de la escalabilidad a partir de las señales disponibles.

Para MCP ordenar por en buscar_anuncios_en_Facebook y encontrar_productos_ganadores, utiliza: pertinencia, fecha de hallazgo, última conexión, adspend, el más longevo, alcanzar, cantidad del conjunto de anuncios, coherencia, visitas mensuales, anuncios activos en la página. Alias creado, fecha, reciente, último_anuncio_iniciado, y primero_anuncio_iniciado MCP las normaliza automáticamente.

Configuración: MCP. Parámetros: MCP · Referencia de herramientas. Para marcas_seguidas, véase Marcas.

Autenticación y medición compartidas (/api/v1/adlibrary, /api/v1/marcas)

Ambos /api/v1/adlibrary y /api/v1/marcas comparten las mismas reglas de medición y autenticación. Marca detalle rutas bajo /api/marcas/* son exclusivas de la sesión; véase Marcas.

  • Clave API: Clave X-API, Autorización: al portador, o ?api_key= (véase Referencia de la API).
  • Sesión: Si el visitante ya ha iniciado sesión, las mismas rutas pueden ejecutarse sin clave; no obstante, el usuario activo debe cumplir con la comprobación de acceso a la API que se indica a continuación.
  • Plan: La cuenta debe incluir Acceso a la API. De lo contrario 403.
  • Créditos / límite de velocidad: Créditos mensuales de API y 60 solicitudes por minuto por usuario. Una vez agotado, 429 con un error JSON y opcional créditos objeto.

Cuando utilizas una clave API sin una sesión de navegador activa, el servidor sigue asociando la clave a tu cuenta para esa solicitud, de modo que el comportamiento coincide con el del panel de control.

GET /api/v1/adlibrary — Lista de anuncios más eficaces de Meta / Facebook

Alias: GET /api/adlibrary — misma medición y los mismos parámetros.

Equivalente en la interfaz de usuario: La llamada de visualizaciones de anuncios de Meta dentro de la aplicación /api/fb-ads (o /api/fb-ads-winning) con la misma estructura de consulta. Para la integración, copia una solicitud activa de la pestaña de red de tu navegador y cambia la ruta a /api/v1/adlibrary (o /api/adlibrary), manteniendo las mismas claves y valores de consulta.

Protección de entradas (claves de consulta obligatorias)

El punto final solo devuelve su carga útil JSON principal cuando todas las claves siguientes están presentes en la cadena de consulta (se permite una cadena vacía):

palabra clave de búsqueda, palabra clave, min, países, de, a, clasificación, filtro de medios, página, máximo, desplazarse, escalado, nichos, desde la última vez que se le vio, tolastseen, estado activo

Si falta alguno, la respuesta no es la carga útil habitual de la lista (evítalo en los clientes).

Además, la puerta interior requiere juicio establecido en la consulta o a ha iniciado sesión / clave API resuelta sesión. Con una Clave X-API, cumples automáticamente con los requisitos de la sesión. De lo contrario, la respuesta es:

{"error":"logged_out"}

Todos de consulta

Todo lo que aparece a continuación se lee desde el cadena de consulta (de la misma forma que /api/fb-ads (en la aplicación).

isset puerta (debe estar presente; se admite una cadena vacía)

La misma lista que Defensa exterior arriba:
palabra clave de búsqueda, palabra clave, min, máximo, países, de, a, clasificación, filtro de medios, página, desplazarse, escalado, nichos, desde la última vez que se le vio, tolastseen, estado activo.

Muy recomendable en todos

El controlador lee sitio web, idiomas, filtro de tipo de página, dirección de ordenación, aplicaciones, y temas sin pasar por eso isset lista. Duplica el panel de control y envía al menos sitio web=Todos, idiomas=Todos, pagetypefilter= (vacío = todos los tipos de página), orden=descendente, apps=Todas, temas=Todos para que el comportamiento se ajuste a la interfaz de usuario y las claves opcionales estén siempre definidas.

Autenticación / sesión /

Parámetro Función
(ninguno) Con Clave X-API, la solicitud se ejecuta con tu cuenta (es como si hubieras iniciado sesión).
juicio Si se establece (p. ej., trial=true), se aplican las reglas de búsqueda de soluciones ganadoras anónimas; si se combinan con filtros en la página ≠ 0, pueden devolver {"message":"need_account"}.

Paginación, cursor, eliminación de

Parámetro Notas
página Índice de páginas que empieza por 0.
desplazarse Cursor de paginación profunda desde la búsqueda; vacío en la primera solicitud, luego se copia el desplazarse valor de la respuesta JSON anterior.
La próxima vez que haya rebajas Unix segundos; se utiliza cuando ordenar=fecha_de_encuentro (La primera página suele utilizar una marca de tiempo de referencia de la interfaz de usuario).
token_de_búsqueda Opcional [a-zA-Z0-9_-]+; corbatas anuncios por marca limitar a una pestaña o búsqueda en la sesión.

por palabra clave

Parámetro Valores permitidos / típicos
palabra clave Texto libre; codificado como URL; convertido a minúsculas en el servidor.
palabra clave de búsqueda '', Todo, URL de destino, nombre de la página, texto del anuncio, nombre del producto (debe estar en este conjunto cuando palabra clave (no está vacía).

Anuncios activos, escalado, medios, tipo de página, AdScore,

Parámetro Valores (que coincidan con los filtros de Meta Ads de la aplicación)
estado activo Cadena verdad o falso (solo activos frente a incluir los inactivos).
escalado '' (ninguno), sin reducción de escala, extrapolación, reducción de escala.
filtro de medios '' / efecto de omisión = todos los formatos; en caso contrario vídeos, imágenes, carrusel, dco (corresponde a formato de visualización (en ES).
filtro de tipo de página '' = todos; productos, colecciones, embudos, nofunnels.
filtro de puntuación publicitaria '' = ninguno; ganador (Fundada), escalado (Tiene potencial), pruebas (Sin determinar). Requiere el nivel correspondiente dentro de la aplicación.
pocas impresiones '' = mostrar todo; ocultar = excluir las filas con un número muy bajo de impresiones (mismo comportamiento que el filtro del panel de control).

Parámetro Valores
dirección de ordenación asc o desc (si está vacío, se establece por defecto en desc).
clasificación '' (Ninguno → orden aleatorio cuando no se baraja), trending, cantidad del conjunto de anuncios, última conexión, fecha de hallazgo, adspend, el más longevo, alcanzar, días corriendo. días corriendo puede que no aplique una rama de ordenación específica (se comporta como None a menos que cambie el producto).

Presupuesto, alcance (con ventana emergente), tráfico, días de publicación, precio, texto publicitario, duración del vídeo, anuncios activos en

Parámetro Notas
gasto en defensa, gasto máximo en publicidad Números enteros / cadenas numéricas. maxadspend=999999 se considera que «no hay límite máximo» a efectos de la comprobación adspend. Para aplicar adspend significativo adspend , puede ser necesario un nivel superior dentro de la aplicación.
periodo de inversión publicitaria todos, 7, 30, 90 — Ventana para adspend (valores no válidos → todos).
minreach, maxreach Números enteros. Puede requerir un nivel superior dentro de la aplicación.
intervalo de tiempo El mismo conjunto permitido que periodo de inversión publicitaria.
mintraffic, maxtraffic Es posible que se requiera un nivel superior dentro de la aplicación.
mindays, días máximos Filtro de rango de días consecutivos; puede requerir un nivel superior dentro de la aplicación.
precio mínimo, precio máximo
longitud del mincópilo, longitud máxima de copia
duración mínima del vídeo, longitud máxima del vídeo
minactiveads, maxactiveads Límite del estilo «Anuncios activos en la página» (el flujo de prueba puede insertar minactiveads (del lado del servidor).

Fechas (cadenas de caracteres, normalmente A-M-D)

Parámetro Significado
de, a Anuncio creación (comenzó).
desde la última vez que se le vio, tolastseen Última vez que se le vio (actualizado el).
producto_de, producto_a Ventana de creación de productos.
página de, página Ventana de creación de páginas.

Los intervalos de fechas abiertos se normalizan en el servidor (por ejemplo, solo de establecer → a se puede configurar para que coincida de).

Catálogo: países, tiendas, nichos, idiomas, aplicaciones, temas,

Parámetro Formato
países Todo o separados por comas ISO 3166-1 alfa-2 códigos (p. ej., EE. UU., Reino Unido).
sitio web Todo o códigos de tienda separados por comas (p. ej., SH = Shopify — (consulte el filtro de sitios web del panel de control).
nichos Todo o segmentos separados por comas (códigos predefinidos, /Ruta/... rutas del catálogo de nichos o identificadores numéricos (normalizados en el servidor). Si la lista contiene compras, el servidor añade producto.
idiomas Todo o códigos de idioma separados por comas (como en el panel de control #idioma).
aplicaciones Todo o separados por comas numérico ID de aplicaciones (los mismos valores que el filtro de aplicaciones integradas).
temas Todo o cadenas de temas separadas por comas (descubrir a través de GET /api/themes).
excluir países, excluir sitios web, excluir idiomas, excluir nichos, excluir aplicaciones Los mismos patrones separados por comas que en el lado de inclusión; nichos normalizados como nichos.

Enlaces directos, reproducción aleatoria,

Parámetro Notas
identificador de página a partir de la URL Facebook page_id: limita los anuncios a una sola página.
id_del_producto ID de producto de Shopify.
barajar Cualquier valor no vacío que se considere verdadero → modo aleatorio (ordenación aleatoria; ventana predeterminada opcional de «último visto»).
anuncios por marca 1, 2, 3, 5, 10 solo: número máximo de anuncios por marca cuando se aplica la lógica de aleatorización o de límite por marca.

Validación /

No válido min o máximo (fuera del intervalo 0…90000000) puede dar como resultado {"error":"value_not_in_range_1"} o _2, o un formato que no sea JSON falso el cuerpo en casos extremos.

Descubrir lo válido nichos y temas (estas rutas no requieren clave API)

Las integraciones deben obtener los valores permitidos del archivo JSON de descubrimiento, no a base de conjeturas:

Punto final Objetivo
GET /api/niche-counts Devoluciones { "niches": [ { "code": "…", "count": N }, … ], "total_with_niche": … } creado a partir del mismo índice de anuncios de Meta que utiliza el producto. Utiliza el código cadenas (separadas por comas en nichos / excluir nichos) como el conjunto de referencia que aparece realmente en los datos publicitarios. Opcional: refresh=1 omite la caché del disco para una solicitud.
GET /api/themes Devuelve un objeto JSON con un temas lista (valores máximos + recuentos, almacenada en caché durante aproximadamente 1 hora). Consulta opcional: q — si la longitud es ≥ 2, búsqueda de subcadenas para autocompletado. Opcional: límite (por defecto 200, máximo 500). Utilizar el tema devuelto nombres/claves exactamente igual que temas= valores separados por comas en /api/adlibrary.

Atajos predefinidos para nichos («chips» de la interfaz de usuario): La aplicación también ofrece funciones orientadas al usuario códigos de dos letras (p. ej., CG, POR, SP) en el filtro de nicho. Esos son segmentos válidos en nichos= del mismo modo que los envía el navegador.

Segmentos de nicho numéricos: Los valores se resuelven utilizando el catálogo de nichos del servidor (rutas como /Ropa/... y numéricos ids (asignación a nombres canónicos en la búsqueda). Si un segmento es desconocido, se puede dejar tal cual — se prefiere /api/recuentos-de-nichos en lugar de inventar excusas.

Nota: /api/recuentos-de-nichos y /api/temas son descubrimiento ayudantes y no consumen créditos de la API de Meta Ad Library de la misma manera /api/adlibrary Es posible que tu implementación siga requiriendo un inicio de sesión u otra política antes de estas rutas.

Funciones (actualización de JSON)

En las cuentas que no cuentan con el nivel de producto requerido, algunos filtros o modos de ordenación devuelven 200 con un cuerpo JSON breve (el mensaje de actualización es dentro de la banda(no siempre un error HTTP 403):

Respuesta Condición (simplificada)
{"upgrade":"standard_adspend"} Se ha aplicado el filtro de gasto publicitario, o adspend
{"upgrade":"standard_reach"} Filtro de alcance o clasificación=alcance
{"upgrade":"standard_traffic"} Filtro de tráfico
{"upgrade":"standard_daysrunning"} Filtro de días consecutivos o ordenar=días consecutivos
{"upgrade":"standard_adscore"} filtro de puntuación publicitaria conjunto

Otras destacadas#

  • {"message":"need_account"} — Anónimo juicio solicitudes que superan el límite de uso permitido (restricciones del flujo de la versión de prueba).
  • Carga útil de éxito: objeto JSON que incluye datos (anuncios), opcional mensaje (sugerencias de filtrado comprensibles para los usuarios), total cuando se calcula en la primera página, y los campos de crédito del plan gratuito, cuando corresponda.