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 :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
Ajoutezinclude.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.
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 à
COMPLETEDdès que la réponse est prête. Continuez d’interroger jusqu’à ce queresponse.citationAnalysis.task.statussoitCOMPLETEDouFAILED. - 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.citationAnalysisvaut{ "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.
Résultat
Les résultats stockés avant la v4 conservent leur forme antérieure, sans champversion.
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 quandownvauttrue).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 commeeditorial.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:truesi la réponse cite la page,falsesi le moteur l’a seulement récupérée.position: le rang attribué à la page par le moteur, ounulls’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, ounull.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 danscitedText.own:truesi 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 unid(unique dans tout le résultat) et letextdu 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.paragraphsest 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 ;nullsi 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 delinks[], 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.
links[] : une relation par paragraphe
paragraphId: le paragraphe concerné par ce lien. Il pointe toujours vers un paragraphe qui existe danssources[].answerRanges[]: les parties de la réponse auxquelles correspond ce paragraphe, en pairesstart/enddans 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 dansbrands[].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: lerankde votre marque dansbrands[].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[].errorest 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 sonbodysi 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_foundsignifie 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.
channelest 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
answerjusqu’à 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[].errorsans 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.