Documentación Adligator API

Empezando

El Adligator API es un RESTful HTTP API. Todos los puntos finales se sirven a través de HTTPS desde el URL base a continuación y devuelven JSON (excepto el punto final de descarga, que responde con una redirección).

https://api.adligator.com/api/v1

1. El acceso a API requiere un Plano Team activo.
2. Cree su clave API en el Portal del desarrollador. La clave se muestra solo una vez; guárdela de forma segura.
3. Pase la clave en el encabezado X-API-Key con cada solicitud.

El API se encuentra actualmente en versión beta y es gratuito. Los límites y los precios pueden cambiar una vez que finalice la versión beta.

¿Quieres probar sin un plan Team? Utilice el Llave de caja de arena API a continuación.

Llave de caja de arena API

Usa la clave pública de sandbox para explorar la API sin un plan Team ni tus propias credenciales. Busca en la biblioteca real de anuncios, restringida a la palabra clave "headway" y a los anuncios vistos por primera vez el 1 de enero de 2026: todos los filtros, el endpoint de detalles y las descargas de medios se comportan exactamente como en producción.

clave de la zona de pruebas:

adl_sandbox000000000000000000000000000000001

como se comporta

• No se requiere plan Team.
• La única palabra clave permitida es headway, pasada en el parámetro body. Se aplica automáticamente si se omite; cualquier otra palabra clave devuelve resultados vacíos.
• Los resultados se limitan a anuncios vistos por primera vez entre 2026-01-01 y 2026-01-02. Los rangos de fechas fuera de esta ventana devuelven resultados vacíos.
• Todos los demás filtros, la paginación, el ordenamiento, los detalles de anuncios y las descargas de medios funcionan con datos reales.
• Se aplican los mismos límites de frecuencia que para las claves de producción.
• La clave de sandbox funciona solo con la API REST; el servidor MCP requiere una clave de producción.
• La búsqueda de páginas de Facebook (GET /fb-pages) siempre devuelve una lista vacía con la clave de sandbox.

Solicitud de ejemplo

curl "https://api.adligator.com/api/v1/ads?body=headway&limit=5" \
  -H "X-API-Key: adl_sandbox000000000000000000000000000000001"

Reemplace la ruta con una identificación de anuncio de la respuesta de búsqueda para llamar a los detalles o descargar.

Autenticación

Autentique cada solicitud con el encabezado X-API-Key. Las claves se parecen a adl_ seguidas de 40 caracteres.

curl "https://api.adligator.com/api/v1/ads?limit=5" \
  -H "X-API-Key: adl_your_api_key_here"

Las solicitudes sin una clave válida se rechazan:

• 401 Unauthorized: falta el encabezado o se desconoce la clave.
• 403 Forbidden: la clave está desactivada o tu plan no incluye el acceso a API.

Límites de frecuencia

Los límites se aplican por clave API y por punto final. Los contadores diarios se reinician a medianoche UTC.

Cada respuesta incluye encabezados de límite de tasa:

X-RateLimit-Limit-Second: 2
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 987

Cuando se excede un límite, el API responde con 429 Too Many Requests y un encabezado Retry-After (en segundos). Las solicitudes rechazadas no cuentan para su cuota diaria.

GET Anuncios de búsqueda

GET /api/v1/ads

Busca en la biblioteca de anuncios. Devuelve una lista paginada con información publicitaria mínima; utilice el punto final de detalles para los descriptores de medios y el punto final de descarga para los archivos originales. Todos los parámetros de consulta son opcionales. Los parámetros de lista aceptan valores separados por comas.

Parámetros de consulta

Solicitud de ejemplo

curl "https://api.adligator.com/api/v1/ads?countries=US,DE&isActive=true&title=fitness&limit=2" \
  -H "X-API-Key: adl_your_api_key_here"

Ejemplo de respuesta

{
  "data": [
    {
      "id": "9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e",
      "isActive": true,
      "displayFormat": 1,
      "publishedOnPlatforms": ["FB", "INST"],
      "countries": ["US", "DE"],
      "countriesAmount": 2,
      "textLanguages": ["en"],
      "startDate": "2026-05-14T00:00:00.000Z",
      "endDate": null,
      "lastSeenAt": "2026-07-03T09:12:44.000Z",
      "activeDaysCount": 50,
      "copiesCount": 12,
      "title": "Get fit in 30 days",
      "linkUrl": "https://example.com/offer",
      "buttonType": "LEARN_MORE",
      "isAAAEligible": true,
      "fbPage": {
        "fbOriginalPageId": "104201234567890",
        "pageName": "Fit Life",
        "pageLikesCount": 53210,
        "profileUri": "https://facebook.com/fitlife"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "totalPages": 187
  }
}

GET Buscar páginas de Facebook

GET /api/v1/fb-pages

Busca páginas de Facebook (anunciantes) por nombre. Úselo para resolver el nombre de una marca, aplicación o producto a un fbOriginalPageId antes de filtrar anuncios por ese anunciante. Devuelve los mejores candidatos con nombre de página, me gusta, enlace de perfil e imagen.

Parámetros de consulta

Solicitud de ejemplo

curl "https://api.adligator.com/api/v1/fb-pages?query=Duolingo&limit=5" \
  -H "X-API-Key: adl_your_api_key_here"

Respuesta de ejemplo

{
  "data": [
    {
      "fbOriginalPageId": "104201234567890",
      "pageName": "Duolingo",
      "pageLikesCount": 12500000,
      "profileUri": "https://facebook.com/duolingo",
      "profilePictureUrl": "https://cdn2.adligator.com/pages/....jpg"
    }
  ],
  "totalCount": 12
}

Pase un fbOriginalPageId devuelto a GET /ads como fbOriginalPageId para obtener los anuncios de ese anunciante.

GET Obtener detalles del anuncio

GET /api/v1/ads/:id

Devuelve información completa para un solo anuncio, incluidos descriptores de medios con vista previa URL. Los objetos multimedia exponen un mediaId que se pasa al punto final de descarga para recuperar el archivo de mayor resolución.

Parámetros de ruta

Solicitud de ejemplo

curl "https://api.adligator.com/api/v1/ads/9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e" \
  -H "X-API-Key: adl_your_api_key_here"

Ejemplo de respuesta

{
  "data": {
    "id": "9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e",
    "isActive": true,
    "displayFormat": 1,
    "publishedOnPlatforms": ["FB", "INST"],
    "countries": ["US", "DE"],
    "title": "Get fit in 30 days",
    "linkUrl": "https://example.com/offer",
    "buttonType": "LEARN_MORE",
    "isAAAEligible": true,
    "adArchiveId": "1234567890123456",
    "categories": [0],
    "bodyHtml": "Join the challenge today...",
    "entityType": "REGULAR",
    "linkDescription": "30-day fitness challenge",
    "caption": "example.com",
    "images": [],
    "videos": [
      {
        "mediaId": "7c2e1f0a-9b8d-4e3c-a1b2-c3d4e5f60789",
        "videoUrl": "https://cdn2.adligator.com/videos/sd/....mp4",
        "previewImageUrl": "https://cdn2.adligator.com/previews/....jpg"
      }
    ],
    "cards": []
  }
}

Los medios URL en esta respuesta tienen calidad de vista previa (imágenes redimensionadas/video SD). Utilice el punto final de descarga para obtener el archivo original.

GET Descargar medios

GET /api/v1/ads/:id/download?mediaId=:mediaId

Resuelve el archivo de mayor resolución (imagen original o video HD) para un elemento multimedia de un anuncio y responde con 302 Found y un encabezado Location apuntando al archivo. Siga la redirección para descargarlo.

Parámetros

Solicitud de ejemplo

curl -L -o creative.mp4 \
  "https://api.adligator.com/api/v1/ads/9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e/download?mediaId=7c2e1f0a-9b8d-4e3c-a1b2-c3d4e5f60789" \
  -H "X-API-Key: adl_your_api_key_here"

Ejemplo de respuesta

HTTP/1.1 302 Found
Location: https://cdn2.adligator.com/videos/hd/....mp4

Errores

Los errores utilizan códigos de estado HTTP convencionales y un cuerpo JSON consistente:

{
  "statusCode": 401,
  "message": "Invalid API key.",
  "error": "Unauthorized"
}