API de mesures en lecture seule

Intégrez vos données de visibilité IA dans vos tableaux de bord, tableurs ou rapports d’agence. JSON ou CSV, une clé par intégration, uniquement les données de votre espace de travail.

Authentification

Créez une clé dans Compte, Clés API (propriétaires de l’espace de travail uniquement). Envoyez-la comme jeton Bearer. La clé complète n’est affichée qu’une fois ; nous n’en gardons qu’une empreinte. Une clé révoquée cesse de fonctionner dès la requête suivante.

curl -H "Authorization: Bearer aeo_YOUR_KEY" \
  "https://YOUR-AEODA-DOMAIN/api/v1/brands/BRAND_ID/scores?from=2026-09-01&limit=50"

# CSV
curl -H "Authorization: Bearer aeo_YOUR_KEY" -o scores.csv \
  "https://YOUR-AEODA-DOMAIN/api/v1/brands/BRAND_ID/scores?format=csv&delimiter=semicolon"

Forfaits

L’API est incluse dans Pro et Agency ; l’export CSV à partir de Starter. En cas de rétrogradation, les clés existantes répondent 403 jusqu’à un nouveau changement de forfait.

En cas de rétrogradation, les clés sont suspendues et répondent 403 ; elles refonctionnent dès que l’espace de travail repasse à un forfait supérieur. Les clés ne sont pas supprimées.

Points de terminaison

Tous les points de terminaison sont en GET et en lecture seule. URL de base : votre domaine aeoda.

Point de terminaison	Renvoie
GET /api/v1/brands	Vos marques (id, nom, domaine, marché).
GET /api/v1/brands/{brandId}/scores	Historique des scores : date, moteur, score, intervalle de confiance, taux de mention.
GET /api/v1/brands/{brandId}/answers	Réponses : prompt, moteur, mentionné ou non, rang, sentiment, concurrents, texte.
GET /api/v1/brands/{brandId}/sources	Sources citées : domaine, URL, nombre de réponses, propre ou concurrent.
GET /api/v1/brands/{brandId}/competitors	Comparaison des concurrents : marque, score, part de voix.
GET /api/v1/brands/{brandId}/recommendations	Plan d’action : titre, priorité, effort, statut.

Paramètres de requête

from et to : dates au format YYYY-MM-DD (par défaut les 30 derniers jours, limités par l’historique de votre forfait). limit : de 1 à 1000 (100 par défaut). cursor : la valeur nextCursor de la page précédente. format : json (par défaut) ou csv. delimiter : comma ou semicolon (CSV). lang : langue des titres de recommandations. Les paramètres inconnus renvoient 400.

Exemple

{
  "data": [
    {
      "brand": "Northwind Coffee",
      "date": "2026-10-01T09:00:00.000Z",
      "engine": "all",
      "score": 55,
      "ci_low": 40,
      "ci_high": 70,
      "mention_rate": 25,
      "sov": 31.5,
      "avg_position": 2.4
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0wMSAwOTowMDowMCswMCIsImlkIjoiLi4uIn0",
  "range": { "from": "2026-09-01", "to": "2026-10-18" }
}

Format CSV

Le CSV est en UTF-8 avec marque d’ordre des octets pour qu’Excel affiche correctement les accents. Les cellules de texte commençant par = + - @ reçoivent une apostrophe pour éviter l’injection de formules. Les réponses CSV sont diffusées en flux et limitées à 100 000 lignes : réduisez la période si vous atteignez la limite (413).

Limites de débit et pagination

Chaque clé autorise 60 requêtes par minute. Les réponses portent x-ratelimit-limit et x-ratelimit-remaining ; un 429 inclut retry-after. Les listes JSON sont paginées avec nextCursor (null sur la dernière page).

format=csv a sa propre limite, plus basse : 6 téléchargements par heure et par clé, et une réponse est plafonnée à 50 Mo (une dernière ligne "# truncated" signale un fichier tronqué).

Erreurs

401Clé absente, mal formée ou révoquée.
403Le forfait de l’espace de travail n’inclut pas l’API.
404La marque n’existe pas dans votre espace de travail.
413Limite de lignes CSV dépassée : utilisez une période plus courte.
429Limite de débit atteinte : attendez le nombre de secondes de retry-after.