Passer au contenu principal
Comparez une réponse IA terminée avec les pages qui la sous-tendent. Le résultat montre les recherches lancées par le moteur, les pages qu’il a récupérées et celles qu’il a citées, les marques que la réponse nomme et les pages qui les nomment, la position de votre marque et des actions prioritaires. Il relie aussi les paragraphes de chaque page citée aux parties de la réponse auxquelles ils correspondent, avec une explication pour chaque lien, et résume ce que les pages citées ont en commun. Il s’agit d’une analyse de correspondance a posteriori d’une réponse existante : elle ne prouve pas qu’une source a amené le modèle à générer une phrase, et elle ne note pas la qualité d’une page. Considérez-la comme un élément à examiner, pas comme un verdict.
Interrogez GET /v1/async/task/:id ou fournissez webhook.url à la soumission ; la tâche indique taskType: "CITATION_ANALYSIS". Ne soumettez pas cette analyse via POST /v1/async/task : utilisez l’endpoint dédié. Les anciens endpoints POST /v1/geo-audit, POST /v1/source-influence et POST /v1/research, les types de tâche GEO_AUDIT, SOURCE_INFLUENCE et CITATION_ATTRIBUTION et include.geoAudit, include.sourceInfluence fonctionnent toujours ; les réponses utilisent toujours les nouveaux noms.

Analyser une tâche déjà exécutée

Si la réponse provient de cette API, envoyez son id de tâche au lieu de copier la réponse et les citations du résultat :
La tâche doit vous appartenir, être COMPLETED et encore lisible via GET /v1/async/task/:id. Son Markdown de réponse (le texte si le moteur n’a pas renvoyé de Markdown) devient answer, et ses URL citées deviennent citations dans l’ordre du moteur : les 100 premières, avec au plus 10 fils de discussion. Les emplacements de fiches produit et vidéo (liens googleusercontent.com) et les liens de recherche Google sont ignorés, faute de page à lire. Le prompt, le country et le moteur de la tâche sont utilisés sauf si vous les envoyez. Envoyer taskId avec answer ou citations est rejeté avec 400, tout comme une tâche inachevée ou sans texte de réponse ni URL citée. Un id de tâche inconnu ou expiré renvoie 404.

Analyser chaque réponse au moment de la collecte

Ajoutez include.citationAnalysis: true à une requête de collecte, et l’analyse s’exécute sur la réponse dès qu’elle est collectée. Cela fonctionne avec les moteurs de réponse (CHATGPT, GEMINI, PERPLEXITY, GOOGLE_AIO, GOOGLE_AIMODE, NAVER_AI_BRIEF, NAVER_AI_TAB, BING_SEARCH, BING_COPILOT), pour les tâches individuelles, les lots de tâches, les grilles et POST /v1/batches.
L’analyse lit la réponse et ses URL citées de la même façon que taskId ci-dessus. Le résultat de la réponse contient alors response.citationAnalysis : la tâche d’analyse telle que la renvoie GET /v1/async/task/:id, avec task, credits et response ou error.
  • Webhook : envoyé une seule fois, une fois l’analyse terminée, avec la réponse et l’analyse ensemble.
  • Interrogation : la tâche de réponse passe à COMPLETED dès que la réponse est prête. Continuez d’interroger jusqu’à ce que response.citationAnalysis.task.status soit COMPLETED ou FAILED.
  • Les lots se terminent lorsque toutes les réponses et leurs analyses sont terminées.
  • Pas d’analyse : si la réponse ne cite aucune URL à lire, ou si vos crédits ou la limite quotidienne de la clé ne couvrent pas la réserve de l’analyse, response.citationAnalysis vaut { "error": "…" } et la réponse est livrée immédiatement.
  • Facturation : l’analyse est facturée à part, à l’usage, comme toute tâche Citation Analysis. Le montant de la réponse ne change pas. Une clé limitée à certains types de tâches doit aussi autoriser CITATION_ANALYSIS.

Payload

Avec taskId ou include.citationAnalysis, ces champs sont remplis à partir des données brutes de la réponse. Pour CHATGPT, les recherches du moteur deviennent queries et chaque page qu’il a récupérée devient une citation avec cited, position, citedText, publishedAt et query ; une même URL avec des paramètres de suivi différents est fusionnée. Pour Google AI Overview, les sources de l’aperçu sont citées et les résultats organiques hors de ces sources sont non cités, avec position égal à leur rang organique. Les autres moteurs ne fournissent que les sources citées.
Envoyer analysis dans la requête renvoie 400. Tous les résultats contiennent des insights.

Résultat

Les résultats stockés avant la v4 conservent leur forme antérieure, sans champ version.

version

Toujours 4 pour cette forme.

answer

La réponse que vous avez soumise, inchangée. answerRanges sont des offsets dans exactement cette chaîne : unités de code UTF-16 JavaScript, start inclus, end exclu. Découpez-la telle quelle, avec answer.slice(start, end), au lieu de redécouper le texte. Chaque plage de links[] désigne une unité sémantique complète de votre réponse : une phrase, un élément de liste ou une cellule de tableau. Chaque plage de brands[] est le nom exact tel qu’il est écrit. Les bornes se réfèrent au texte d’origine.

queries[]

Les recherches lancées par le moteur pour cette réponse. Chacune a un id, son text et sourceIds : les sources trouvées par cette recherche. Vide si le moteur n’a exposé aucune recherche et que vous n’en avez envoyé aucune.

sources[] : une entrée par page

  • id : identifiant opaque, unique dans le résultat.
  • url : l’URL de la page ; domain : son hôte.
  • channel : qui contrôle la page, déduit de son hôte :
    • own : le site propre de votre marque (exactement quand own vaut true).
    • brand : le site propre d’une autre marque nommée dans le résultat.
    • editorial : un éditeur ; seul l’éditeur peut modifier la page. Les hôtes non reconnus sont signalés comme editorial.
    • retailer : une boutique en ligne ou une marketplace.
    • review_platform : un site d’avis de clients ou d’entreprises.
    • community : un forum ou un site de questions-réponses.
    • video : une plateforme vidéo.
    • social : un réseau social.
    • blog_platform : un service de blogs hébergés.
    • reference : une encyclopédie ou un wiki ; jamais la cible d’une action.
  • cited : true si la réponse cite la page, false si le moteur l’a seulement récupérée.
  • position : le rang attribué à la page par le moteur, ou null s’il n’en a donné aucun.
  • queryIds[] : les recherches qui ont trouvé la page.
  • publishedAt : la date de publication telle que le moteur l’a indiquée, ou null.
  • citedText[] : les passages que le moteur lui-même indique avoir cités ; [] s’il n’y en a aucun.
  • brandIds[] : les marques nommées sur la page lisible, dans son titre ou dans citedText.
  • own : true si la page se trouve sur le site propre de votre marque.
  • paragraphs[] : les paragraphes d’une page citée inclus dans le résultat. Chacun a un id (unique dans tout le résultat) et le text du paragraphe. Un paragraphe peut être inclus sans aucun lien. Toujours vide pour les pages non citées.
  • error : présent uniquement si la page n’a pas pu être lue. paragraphs est alors vide, et la chaîne donne une courte raison pour cette source.

brands[]

Toutes les marques suivies par le résultat : votre brand (role: "target"), vos competitors ("competitor") et les autres marques que la réponse nomme ("answer").
  • rank : l’ordre de la première occurrence du nom de la marque dans la réponse, à partir de 1 ; null si la réponse ne nomme pas la marque.
  • answerRanges[] : les passages exacts où la réponse nomme la marque ou l’un de ses noms de produit, dans les mêmes offsets UTF-16 ; answer.slice(start, end) renvoie le nom tel qu’il est écrit. La recherche ignore la casse et porte sur des mots entiers (sauf dans les écritures sans espaces) ; elle couvre les titres et les cellules de tableau, jamais les URL de liens ni le balisage d’images. Contrairement aux plages de links[], ce ne sont pas des unités complètes de la réponse.
  • citedSourceIds[] : les sources citées dont la page la nomme.
  • retrievedSourceIds[] : les sources non citées dont la page la nomme.
  • ownSourceIds[] : les sources sur le site propre de la marque ; rempli uniquement pour la cible.
  • paragraphId : le paragraphe concerné par ce lien. Il pointe toujours vers un paragraphe qui existe dans sources[].
  • answerRanges[] : les parties de la réponse auxquelles correspond ce paragraphe, en paires start/end dans les mêmes offsets UTF-16. Un lien peut porter plusieurs plages ; le même texte de réponse n’est pas répété entre elles. Chaque plage est une unité complète de la réponse (phrase, élément de liste ou cellule de tableau).
  • explanation : une courte phrase décrivant la correspondance, c’est-à-dire ce que le paragraphe affirme sur cette partie de la réponse.

visibility

La position de votre marque dans cette réponse ; null si aucune brand n’a été envoyée.
  • brandId : votre marque dans brands[].
  • stage : l’une des valeurs suivantes :
    • mentioned : la réponse nomme votre marque.
    • on_cited_page : la réponse ne la nomme pas, mais une page citée la nomme.
    • on_retrieved_page : seules des pages récupérées sans être citées par le moteur la nomment.
    • not_found : aucune page lue ne la nomme.
  • rank : le rank de votre marque dans brands[].
  • answerBrands : le nombre de marques que la réponse nomme.

actions[]

Les prochaines étapes prioritaires pour votre marque ; [] si aucune brand n’a été envoyée. priority commence à 1 (à faire en premier) et ne présente aucun trou. Les actions sont ordonnées par control : d’abord ce que votre marque contrôle (owned), puis les plateformes où elle peut publier (platform), puis la prise de contact (outreach). summary tient en une phrase et steps[] contient une à cinq étapes concrètes, tous deux dans la langue de la réponse. sourceIds, brandIds, queryIds et linkIds pointent vers les éléments de preuve de ce résultat. brandIds nomme votre marque, ou les marques concurrentes que nomment ces pages. Les actions ne suggèrent jamais de faux avis ou d’avis non déclarés, de se faire passer pour un évaluateur indépendant, d’acheter des liens ni de modifier des pages que votre marque ne possède pas. Les pages tierces qui nomment votre marque sans être citées figurent dans brands[].retrievedSourceIds, pas parmi les actions.

insights[]

Jusqu’à quatre courts résumés de ce que les pages révèlent ensemble : quels canaux ont été cités, le format, la fraîcheur ou les critères que partagent les pages citées, comment l’ordre des marques dans la réponse se compare à ce que couvrent les pages citées, et où se situe votre marque. sourceIds nomme les pages et linkIds les liens sur lesquels repose chaque résumé ; au moins l’un des deux est non vide, et ils ne nomment que des entrées de ce résultat. Les insights décrivent une correspondance ; ce ne sont pas des conseils.

Bien lire le résultat

  • L’absence de lien n’est pas un verdict. Un paragraphe sans lien n’a simplement pas correspondu à une plage de la réponse, et une partie de la réponse sans plage signifie qu’aucun paragraphe n’y a été relié. Ni l’un ni l’autre ne dit que la page est hors sujet, inutilisée ou peu fiable.
  • Une page non lue reste incertaine. Si sources[].error est défini, cette citation a été exclue de l’analyse ; ne traitez pas son absence de liens comme un constat négatif. Relancez-la ou fournissez son body si elle compte.
  • Correspondance, pas causalité. Le résultat décrit comment une réponse existante et le texte de pages existantes se recoupent après coup, et quelles marques ces pages nomment. Il ne mesure pas l’influence sur la génération, ne note pas la page et n’indique pas comment la réponse a été produite.
  • not_found signifie absente de toutes les pages lues. Cela ne veut pas dire que votre marque est absente du web.
  • Les données de récupération dépendent du moteur. Les pages non citées n’apparaissent que si le moteur les expose (ChatGPT, Google AI Overview) ou si vous envoyez des pages cited: false. Sinon, toutes les sources sont citées, et votre propre page ne peut apparaître que comme citée.
  • Les canaux sont déduits de l’hôte. channel est déduit de l’hôte de la page, pas d’une lecture de qui l’a écrite.
  • Les actions sont des suggestions, pas des garanties. Elles sont priorisées à partir des pages listées dans ce résultat ; en appliquer une ne garantit pas que la réponse change.
  • Les ids sont internes. Ne conservez pas les identifiants s…/q…/b…/l…/a… comme clés stables d’une exécution à l’autre ; ils ne valent qu’au sein d’un résultat.

Exécution et limites

  • La taille n’est pas un motif d’échec. Tout ce que le contrat de requête accepte, une answer jusqu’à 200 000 caractères avec jusqu’à 100 citations, est analysé. Les réponses longues, les grands ensembles de sources et les pages très longues sont traités en découpant le travail, pas en rejetant la tâche.
  • La profondeur suit la réponse, pas la page. Une page longue ne produit pas plus de liens que la réponse ne peut en justifier : l’analyse se concentre sur les passages les plus susceptibles de correspondre à la réponse, et chaque source qui montre une correspondance est représentée. Sur une grande page, ou sur une page qui répète la même affirmation dans la navigation, les listes et les avis, attendez-vous aux passages les plus forts plutôt qu’à chaque occurrence.
  • Le balisage n’est pas une preuve. Les plans de site, index de liens et galeries d’images ne produisent aucun lien ; une page constituée uniquement de ces éléments est signalée sans paragraphe plutôt qu’avec des correspondances inventées.
  • Une source illisible est signalée dans sources[].error sans faire échouer la tâche si une autre source est lisible. La tâche échoue quand aucune source n’a pu être lue, en cas d’échec de l’analyse, de timeout ou d’erreur de configuration du service.
  • Les requêtes sont facturées à l’usage, comme le reste de l’API. La réponse de soumission indique la réservation temporaire de crédits ; le montant final est réglé quand la tâche atteint un état final.