Synupv1
Créer une clé
v1Ressources/AEO

AEO

Suivez la visibilité d'un établissement dans les moteurs de réponse IA (ChatGPT, Gemini, Perplexity) : à quelle fréquence il est mentionné, son classement face aux concurrents, et ce qui freine son score.

Renvoie le dernier rapport de visibilité IA d'un établissement : scores global et par moteur, la matrice mots-clés/prompts, les comparaisons d'écart et de classement concurrentiel, la couverture des citations, le sentiment et les corrections recommandées. La génération de rapport est asynchrone — cet endpoint est aussi la cible d'interrogation pour POST /api/v1/aeo/reports/enqueue : continuez à l'appeler et surveillez le champ generating jusqu'à ce qu'il repasse à false et que generatedAt se mette à jour. Passez prompt pour explorer un seul prompt suivi au lieu du rapport complet.

Obtenir le rapport AEO d'un établissement

get/api/v1/aeo/reports
aeo:read
Paramètres de requête
locationIdstringobligatoire
L'établissement à consulter.
clientIdstringfacultatif
Le client de l'établissement.
promptstringfacultatif
Explore un seul prompt suivi (comparé sans distinction de casse) au lieu de renvoyer le rapport complet. Renvoie des cellules null si le prompt n'est pas dans la matrice de cet établissement.
Réponse
dataobjectfacultatif
Erreurs
400Il manque un paramètre requis à la requête, ou elle est invalide.
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
404La ressource est introuvable, ou n'appartient pas à votre agence.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
get/api/v1/aeo/reports
Votre clé API
locationId *
clientId
prompt
{
  "data": {
    "generatedAt": "2026-02-01T06:00:00.000Z",
    "generating": false,
    "configuredEngines": [
      "ChatGPT",
      "Gemini"
    ],
    "visibility": {
      "overall": 62,
      "label": "GOOD",
      "message": "Your business shows up for most of the prompts you're tracking.",
      "engines": {
        "ChatGPT": {
          "score": 68,
          "comparisonPct": 12,
          "configured": true
        },
        "Gemini": {
          "score": 56,
          "comparisonPct": -4,
          "configured": true
        },
        "Perplexity": {
          "score": null,
          "comparisonPct": null,
          "configured": false
        }
      }
    },
    "metrics": {
      "visibility": {
        "value": 62,
        "delta": 5
      },
      "mentionRate": {
        "value": 71,
        "delta": 3
      },
      "avgPosition": {
        "value": 2.1,
        "delta": -0.4
      },
      "promptsCovered": {
        "value": 8,
        "total": 10
      },
      "sourcesCited": {
        "value": 14,
        "delta": 2
      }
    },
    "keywordMap": {
      "ChatGPT": [
        {
          "keyword": "best dentist austin",
          "percentage": 82,
          "dataSources": [
            {
              "name": "Google Business Profile"
            }
          ]
        }
      ],
      "Gemini": [
        {
          "keyword": "emergency dentist austin",
          "percentage": 54,
          "dataSources": []
        }
      ],
      "Perplexity": []
    },
    "matrix": [
      {
        "keyword": "best dentist austin",
        "cells": {
          "ChatGPT": {
            "score": 82,
            "mentioned": true,
            "rank": 1,
            "answerExcerpt": "Acme Dental — Downtown is highly rated for..."
          },
          "Gemini": {
            "score": 54,
            "mentioned": true,
            "rank": 3,
            "answerExcerpt": null
          },
          "Perplexity": null
        },
        "best": 82
      }
    ],
    "gap": [
      {
        "business": "Acme Dental — Downtown",
        "isYou": true,
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "comparisonPct": null
      },
      {
        "business": "Smile Bright Dental",
        "isYou": false,
        "overall": 71,
        "chatgpt": 74,
        "gemini": 68,
        "perplexity": null,
        "comparisonPct": 9
      }
    ],
    "ranking": {
      "All": {
        "primary": {
          "good": 6,
          "neutral": 2,
          "bad": 2
        },
        "competitors": []
      },
      "ChatGPT": {
        "primary": {
          "good": 7,
          "neutral": 1,
          "bad": 2
        },
        "competitors": []
      },
      "Gemini": {
        "primary": {
          "good": 5,
          "neutral": 3,
          "bad": 2
        },
        "competitors": []
      },
      "Perplexity": {
        "primary": {
          "good": 0,
          "neutral": 0,
          "bad": 0
        },
        "competitors": []
      }
    },
    "radar": {
      "ChatGPT": {
        "relevance": 78,
        "reviews": 88,
        "engagement": 65,
        "freshness": 74,
        "citations": 81
      },
      "Gemini": {
        "relevance": 70,
        "reviews": 80,
        "engagement": 75,
        "freshness": 85,
        "citations": 65
      },
      "Perplexity": {
        "relevance": 0,
        "reviews": 0,
        "engagement": 0,
        "freshness": 0,
        "citations": 0
      }
    },
    "factors": [
      {
        "key": "citations",
        "label": "Citations",
        "value": 81,
        "detail": "Cited by 14 of 20 tracked sources across configured engines.",
        "action": {
          "label": "Fix missing citations",
          "target": "citations"
        }
      }
    ],
    "citations": {
      "summary": {
        "totalSources": 20,
        "active": 14,
        "detected": 4,
        "missing": 2,
        "missingDirectories": [
          "Yelp"
        ]
      },
      "byEngine": {
        "ChatGPT": [
          {
            "name": "Google Business Profile",
            "status": "active"
          }
        ],
        "Gemini": [],
        "Perplexity": []
      }
    },
    "sentiment": {
      "positive": 62,
      "neutral": 30,
      "negative": 8,
      "mentions": []
    },
    "attention": [
      {
        "text": "Bing Places is missing your current hours.",
        "tone": "warn"
      }
    ],
    "recommendations": [
      {
        "id": "rec_reviews_1",
        "kind": "opportunity",
        "priority": "high",
        "title": "Add more customer reviews mentioning services",
        "detail": "Reviews that name specific services improve how often engines cite you for those prompts.",
        "action": {
          "label": "Request reviews",
          "target": "reviews"
        }
      }
    ],
    "history": [
      {
        "yearMonth": "2026-01",
        "overall": 57,
        "chatgpt": 61,
        "gemini": 53,
        "perplexity": null,
        "sources": 12
      },
      {
        "yearMonth": "2026-02",
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "sources": 14
      }
    ],
    "competitorHistory": [
      {
        "name": "Smile Bright Dental",
        "points": [
          {
            "yearMonth": "2026-01",
            "overall": 65
          },
          {
            "yearMonth": "2026-02",
            "overall": 71
          }
        ]
      }
    ]
  }
}
v1Ressources/AEO/postMettre en file la génération d'un rapport AEO

Démarre une génération en arrière-plan d'un nouveau rapport AEO pour un établissement. La génération de rapport exécute plusieurs appels LLM par moteur/prompt et ne s'exécute jamais de façon synchrone dans la requête — cet appel met le job en file et renvoie immédiatement. Il n'existe pas de ressource séparée d'id de job ou de statut : interrogez GET /api/v1/aeo/reports pour le même établissement et surveillez le champ generating jusqu'à ce qu'il repasse à false. Non disponible pour les établissements antérieurs au cache d'établissement legacy de Synup (établissements natifs uniquement).

Mettre en file la génération d'un rapport AEO

post/api/v1/aeo/reports/enqueue
aeo:write
Corps de la requête
locationIdstringobligatoire
L'établissement pour lequel générer un rapport.
clientIdstringfacultatif
Le client de l'établissement.
forcebooleanfacultatif
Quand true, démarre une nouvelle génération même si un rapport a déjà été généré ce mois-ci.
Réponse
dataobjectfacultatif
enqueuedbooleanfacultatif
Toujours true — le job de génération a été mis en file.
forcebooleanfacultatif
Renvoie l'indicateur force de la requête.
Erreurs
400Il manque un paramètre requis à la requête, ou elle est invalide.
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
404La ressource est introuvable, ou n'appartient pas à votre agence.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
post/api/v1/aeo/reports/enqueue
Votre clé API
Corps de la requête*
{
  "data": {
    "enqueued": true,
    "force": false
  }
}
v1Ressources/AEO/getObtenir la synthèse AEO tous établissements

Renvoie la synthèse du dernier rapport AEO par établissement, éventuellement restreinte à un client et/ou à des tags d'établissement, ainsi que la tendance de portefeuille et les données de correction systémique. Les établissements sans rapport encore affichent des scores null.

Obtenir la synthèse AEO tous établissements

get/api/v1/aeo/rollup
aeo:read
Paramètres de requête
clientIdstringfacultatif
Restreint les résultats à un client. Quand votre clé est limitée à des clients spécifiques, ceci est obligatoire.
tagsstringfacultatif
Noms de tags d'établissement séparés par des virgules. Seuls les établissements portant au moins un de ces tags sont inclus.
Réponse
dataobjectfacultatif
rowsarray of objectfacultatif
Une ligne par établissement dans le périmètre.
locationIdstringfacultatif
Identifiant unique de l'établissement.
namestringfacultatif
Le nom commercial de l'établissement.
citystringfacultatif
Ville, ou null.
overallnumberfacultatif
Dernier score de visibilité IA global (0 à 100), ou null si jamais généré.
chatgptnumberfacultatif
Dernier score ChatGPT, ou null.
gemininumberfacultatif
Dernier score Gemini, ou null.
perplexitynumberfacultatif
Dernier score Perplexity, ou null.
generatedAtstringfacultatif
Date de génération du dernier rapport, au format horodatage ISO 8601, ou null si jamais généré.
yearMonthstringfacultatif
Mois du dernier rapport (YYYY-MM), ou null.
tagsarray of stringfacultatif
Les tags internes de l'établissement.
historyarray of numberfacultatif
Historique du score global pour cet établissement, chronologique, valeurs non nulles uniquement.
deltanumberfacultatif
Variation du score global par rapport au rapport précédent, ou null sur le premier rapport ou s'il n'y a pas de mois précédent.
topIssueobjectfacultatif
Le facteur de visibilité le plus faible de cet établissement, ou null s'il n'a pas encore de rapport.
labelstringfacultatif
tonestring (good | warn | bad)facultatif
configuredEnginesarray of string (ChatGPT | Gemini | Perplexity)facultatif
Moteurs IA pour lesquels cette agence a une clé API configurée.
portfolioHistoryarray of objectfacultatif
Score global moyen sur les établissements du périmètre, par mois.
yearMonthstringfacultatif
Mois au format YYYY-MM.
avgnumberfacultatif
Score global moyen sur les établissements ayant un rapport ce mois-là.
locationsnumberfacultatif
Nombre d'établissements ayant un rapport ce mois-là (le dénominateur de la moyenne).
systemicFixesarray of objectfacultatif
Faiblesses transversales partagées par plusieurs établissements, chacune avec une correction groupée unique, classées par portée.
factorstringfacultatif
Identifiant de facteur lisible par une machine.
labelstringfacultatif
Nom de facteur lisible par un humain.
detailstringfacultatif
Explication de la faiblesse systémique.
targetstring (listings | citations | reviews | posts | competitors | prompts)facultatif
Vers quelle partie du produit la correction mène.
countnumberfacultatif
Nombre d'établissements concernés.
pctnumberfacultatif
Pourcentage d'établissements en rapport concernés.
Erreurs
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
get/api/v1/aeo/rollup
Votre clé API
clientId
tags
{
  "data": {
    "rows": [
      {
        "locationId": "cm_loc_1",
        "name": "Acme Dental — Downtown",
        "city": "Austin",
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "generatedAt": "2026-02-01T06:00:00.000Z",
        "yearMonth": "2026-02",
        "tags": [
          "priority"
        ],
        "history": [
          57,
          62
        ],
        "delta": 5,
        "topIssue": null
      }
    ],
    "configuredEngines": [
      "ChatGPT",
      "Gemini"
    ],
    "portfolioHistory": [
      {
        "yearMonth": "2026-01",
        "avg": 57,
        "locations": 5
      },
      {
        "yearMonth": "2026-02",
        "avg": 62,
        "locations": 5
      }
    ],
    "systemicFixes": [
      {
        "factor": "citations",
        "label": "Citations",
        "detail": "6 locations are missing citations on Yelp.",
        "target": "citations",
        "count": 6,
        "pct": 30
      }
    ]
  }
}