Documentation Adligator API

Commencer

Le Adligator API est un RESTful HTTP API. Tous les points de terminaison sont servis sur HTTPS à partir de la base URL ci-dessous et renvoient JSON (à l'exception du point de terminaison de téléchargement, qui répond par une redirection).

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

1. L'accès au API nécessite un Plan Team actif.
2. Créez votre clé API dans le Portail des développeurs. La clé n'est affichée qu'une seule fois : conservez-la en toute sécurité.
3. Transmettez la clé dans l’en-tête X-API-Key à chaque requête.

Le API est actuellement en version bêta et gratuit. Les limites et les prix peuvent changer une fois la version bêta terminée.

Vous voulez essayer sans forfait Team ? Utilisez le Clé du bac à sable API ci-dessous.

Clé du bac à sable API

Utilisez la clé publique sandbox pour explorer l'API sans plan Team ni vos propres identifiants. Elle interroge la vraie bibliothèque d'annonces, restreinte au mot-clé "headway" et aux annonces vues pour la première fois le 1er janvier 2026 — tous les filtres, l'endpoint de détails et les téléchargements de médias se comportent exactement comme en production.

Clé du bac à sable:

adl_sandbox000000000000000000000000000000001

Comment il se comporte

• Aucun plan Team requis.
• Le seul mot-clé autorisé est headway, passé dans le paramètre body. Il est appliqué automatiquement s'il est omis ; tout autre mot-clé renvoie des résultats vides.
• Les résultats sont limités aux annonces vues pour la première fois entre 2026-01-01 et 2026-01-02. Les plages de dates en dehors de cette fenêtre renvoient des résultats vides.
• Tous les autres filtres, la pagination, le tri, les détails d'annonces et les téléchargements de médias fonctionnent avec des données réelles.
• Les mêmes limites de débit s'appliquent que pour les clés de production.
• La clé sandbox fonctionne uniquement avec l'API REST ; le serveur MCP nécessite une clé de production.
• La recherche de pages Facebook (GET /fb-pages) renvoie toujours une liste vide avec la clé sandbox.

Exemple de demande

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

Remplacez le chemin par un identifiant d'annonce issu de la réponse de recherche pour appeler les détails ou télécharger.

Authentification

Authentifiez chaque demande avec l'en-tête X-API-Key. Les clés ressemblent à adl_ suivies de 40 caractères.

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

Les demandes sans clé valide sont rejetées :

• 401 Unauthorized — l'en-tête est manquant ou la clé est inconnue.
• 403 Forbidden — la clé est désactivée ou votre forfait n'inclut pas l'accès API.

Limites de débit

Les limites sont appliquées par clé API et par point de terminaison. Les compteurs journaliers sont réinitialisés à minuit UTC.

Chaque réponse inclut des en-têtes de limite de débit :

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

Lorsqu'une limite est dépassée, le API répond avec 429 Too Many Requests et un en-tête Retry-After (en secondes). Les demandes rejetées ne comptent pas dans votre quota quotidien.

GET Rechercher des annonces

GET /api/v1/ads

Recherche dans la bibliothèque d'annonces. Renvoie une liste paginée avec un minimum d'informations sur les annonces ; utilisez le point de terminaison de détails pour les descripteurs de médias et le point de terminaison de téléchargement pour les fichiers originaux. Tous les paramètres de requête sont facultatifs. Les paramètres de liste acceptent les valeurs séparées par des virgules.

Paramètres de requête

Exemple de demande

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"

Exemple de réponse

{
  "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 Rechercher des pages Facebook

GET /api/v1/fb-pages

Recherche des pages Facebook (annonceurs) par nom. Utilisez-la pour résoudre le nom d'une marque, d'une application ou d'un produit en fbOriginalPageId avant de filtrer les annonces par cet annonceur. Renvoie les meilleurs candidats avec le nom de la page, les likes, le lien du profil et l'image.

Paramètres de requête

Exemple de demande

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

Exemple de réponse

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

Passez un fbOriginalPageId renvoyé à GET /ads comme fbOriginalPageId pour récupérer les annonces de cet annonceur.

GET Obtenir les détails de l'annonce

GET /api/v1/ads/:id

Renvoie des informations complètes sur une seule annonce, y compris les descripteurs de médias avec l'aperçu URL. Les objets multimédia exposent un mediaId que vous transmettez au point de terminaison de téléchargement pour récupérer le fichier de la plus haute résolution.

Paramètres du chemin

Exemple de demande

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

Exemple de réponse

{
  "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": []
  }
}

Les médias URL dans cette réponse sont en qualité d'aperçu (images redimensionnées / vidéo SD). Utilisez le point de terminaison de téléchargement pour obtenir le fichier d'origine.

GET Télécharger des médias

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

Résout le fichier de la plus haute résolution (image originale ou vidéo HD) pour un élément multimédia d'une annonce et répond avec 302 Found et un en-tête Location pointant vers le fichier. Suivez la redirection pour le télécharger.

Paramètres

Exemple de demande

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"

Exemple de réponse

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

Erreurs

Les erreurs utilisent des codes d'état HTTP conventionnels et un corps JSON cohérent :

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