API de suivi GEO : mentions et citations de marque

​

Qu’est-ce qu’un moniteur

• Elle enregistre si un alias de marque apparaît dans le texte de la réponse et à quel offset de caractère ; si la réponse a cité l’un de vos domaines enregistrés ; et lesquels de vos concurrents configurés sont apparus dans la même réponse.
• Elle ne produit pas de score de sentiment ni d’estimation de part de marché. Un rang est une place parmi les marques que citent les réponses, comme dans le classement d’un moniteur de catégorie (voir plus bas).

​

Les concurrents sont trouvés pour vous

• Les concurrents trouvés portent source: "auto". Ceux que vous ajoutez portent source: "user", et la lecture ne les modifie ni ne les supprime jamais.
• Quand la liste trouvée change, les réponses enregistrées du moniteur sont recomptées avec elle, afin que chaque marque d’un rapport soit mesurée sur les mêmes réponses. competitorsReadAt sur le moniteur indique la date de la dernière lecture.
• Les noms en alphabet latin correspondent à des mots entiers : « replicates » ne compte pas comme une mention de la marque Replicate.

​

Séparez les moniteurs de façon réfléchie

• Un moniteur par sujet et par marché, pour que la cohorte d’un rapport reste comparable. Mélanger « meilleur CRM » et « comment fixer le prix d’un CRM » dans un même jeu fait la moyenne de deux intentions différentes en un seul chiffre.
• Formulez les prompts comme un acheteur et n’y mettez jamais votre propre marque. Un prompt contenant la marque est toujours une mention : il affiche 100 % pour toujours et ne mesure rien. Les noms de concurrents conviennent et font souvent les prompts les plus utiles.

​

Moniteurs de catégorie : classez les marques d’un marché

curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Sunscreen market",
    "mode": "CATEGORY",
    "category": "Sunscreen",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best sunscreen for sensitive skin", "best sunscreen for kids"],
    "promptTopics": {
      "best sunscreen for sensitive skin": "Sensitive skin",
      "best sunscreen for kids": "Kids"
    },
    "competitors": [{ "name": "Supergoop" }, { "name": "La Roche-Posay", "aliases": ["LRP"] }],
    "country": "US",
    "intervalHours": 24
  }'

​

Ce que classe le rapport

• rank ordonne les marques selon le nombre de réponses qui les citent : c’est une place parmi les marques que citent ces réponses. Une marque qu’aucune réponse n’a citée a rank: null.
• Le mentionRate d’une marque se divise par son propre sampleSize, les réponses notées pendant que la marque figurait dans la liste. Une marque ajoutée aujourd’hui est mesurée à partir d’aujourd’hui.
• shareOfVoice vaut 100 × mentions de cette marque / toutes les mentions de marques suivies dans la fenêtre : les parts d’une même fenêtre totalisent donc 100.
• GET /v1/monitors ajoute leader (la marque la plus citée, avec son taux) à chaque moniteur de catégorie. Ses compteurs mentioned et cited valent toujours 0.
• GET /v1/monitors/{id}/answers/{taskId} renvoie mode, un aliases vide et les marques suivies comme competitors.

​

Rechercher des prompts à partir de la demande de recherche

curl -X POST "$BASE/v1/monitors/research" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "seed": "sunscreen", "country": "US", "monitorSize": 10, "monitorEngines": ["CHATGPT", "GEMINI"] }'

​

Coût et calendrier

credits per run  = prompts × sum(credits for each engine)
credits / month  ≈ credits per run × (24 × 30) / intervalHours

• Une exécution n’est pas une rafale. Les tâches sont admises au rythme que permettent la concurrence de l’offre et la file : une exécution qui dépasse la limite d’une offre gratuite arrive sur plusieurs minutes au lieu d’être abandonnée. Surveillez health.pending dans un rapport pour voir une exécution en cours.
• La fenêtre suivante est un horaire, pas une garantie. nextRunAt est le moment où l’exécution est due ; un moniteur en pause pendant une semaine reprend un intervalle après sa réactivation au lieu de lancer les exécutions manquées.

​

Endpoints

​

Créer un moniteur

curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Earbud brand tracking",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best wireless earbuds for commuting", "are cheap earbuds worth it"],
    "aliases": ["Acme Audio", "Acme"],
    "domains": ["example.com"],
    "competitors": [{ "name": "Sony", "aliases": ["Sony"] }],
    "country": "US",
    "intervalHours": 24
  }'

​

L’exécuter, puis lire le rapport

​

Ce que signifient les chiffres

• mentionRate pour la fenêtre, ses groupes par moteur et ses groupes par cellule vaut 100 × réponses avec mention / réponses notées. Il est pondéré par les réponses, pas une moyenne des taux par moteur : un moteur très actif ne peut pas être écrasé par un moteur peu actif. (Le taux propre d’une marque a son propre dénominateur, expliqué ci-dessous.)
• citationRate a la même forme pour les réponses qui ont cité l’un de vos domaines enregistrés. Sans domaine enregistré, il vaut toujours zéro, car le suivi des citations est désactivé.
• Le taux d’une marque se divise par son propre sampleSize, pas par le total de la fenêtre. Pour votre marque, ce sont toutes les réponses notées ; pour un concurrent, seulement les réponses notées pendant qu’il figurait sur le moniteur. Ajoutez un concurrent aujourd’hui et son premier rapport couvre les réponses qui l’ont mesuré : l’historique antérieur ne compte pas contre lui. Une marque sans réponse éligible affiche mentionRate: null, pas 0 %, car 0 % se lirait comme une vraie disparition.
• shareOfVoice dans brands vaut 100 × mentions de cette marque / toutes les mentions des marques suivies sur la fenêtre : les parts d’une fenêtre totalisent donc 100. Il compare les marques au sein des réponses que vous avez collectées pour ces prompts ; ce n’est ni une part de marché ni un classement de visibilité. Le shareOfVoice de l’endpoint de détail hérité est l’ancienne vue de pénétration des réponses, où chaque marque est comptée par rapport aux réponses collectées et où le total peut dépasser 100 : ne mélangez pas les deux dans un même graphique.
• competitorOnly (et la liste opportunities) compte les réponses qui ont nommé un concurrent configuré alors que votre marque était absente. C’est l’écart sur lequel vous pouvez agir.
• Les taux sont nullables, pas nuls. Aucune réponse dans la fenêtre donne null ; un taux de zéro signifie qu’il y a eu des réponses et qu’aucune ne correspondait.
• Une observation terminée sans réponse compte comme non mentionnée. Elle reste dans le dénominateur, et quality.noAnswerObservations indique combien il y en a eu. Une tâche échouée est exclue de tous les taux et n’apparaît que dans health : un moteur en panne réduit l’échantillon au lieu de devenir silencieusement une absence, et quality ne la reconstruit jamais comme telle (historicalFailures vaut toujours null).
• Les variations sont masquées quand elles induiraient en erreur. changes et le mentionRateChangePp par cellule valent null, et quality.comparable vaut false, lorsqu’une période n’a aucune réponse (insufficient_periods), lorsque des lignes ont été notées avant l’existence du contexte de notation (legacy_scoring_unknown), ou lorsque la définition de notation a changé entre les périodes (scoring_definitions_changed). Les lignes historiques gardent les définitions avec lesquelles elles ont été notées (quality.scoring) : modifier vos alias ou concurrents ne réécrit jamais le passé. Seule exception : la lecture mensuelle des concurrents décrite plus haut.
• La taille d’échantillon est publiée. quality.lowSample est true en dessous de 30 réponses notées, quality.missingCells compte les cellules prompt × moteur configurées encore sans réponse, et quality.partialDays nomme les jours UTC que la fenêtre coupe en deux : le comptage plus faible d’un jour partiel est arithmétique, pas un déclin.

​

D’où viennent les réponses

​

Citations dans le temps

curl "$BASE/v1/monitors/$MONITOR_ID/citations?days=30&kind=owned" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

​

Exporter les lignes notées

​

Lire la réponse derrière un chiffre

• answerText : la réponse telle que le moteur l’a donnée, en markdown si disponible, 8 000 caractères au plus, coupée avec des points de suspension si elle était plus longue.
• sources : les citations dans l’ordre du moteur, chacune avec son libellé et sa position (à partir de 1) dans cette liste.
• aliases et competitors : ce à quoi cette ligne a été comparée, pour que la mention puisse être vérifiée plutôt que crue sur parole.
• scoringContext : la définition exacte utilisée, avec un hash version, l’heure de notation, answerPresent et evidenceTruncated quand le texte ci-dessus a été coupé.

​

Erreurs sur cette surface

​

Un agent dans la boucle

1. GET /v1/monitors/capabilities : lisez les moteurs, les prix et les limites avant de dépenser quoi que ce soit.
2. GET /v1/monitors : réutilisez un moniteur existant pour le sujet et le marché, ou POST /v1/monitors pour en créer un (en appelant éventuellement d’abord POST /v1/monitors/suggest et en modifiant les candidats).
3. POST /v1/monitors/{id}/run : si vous avez besoin de réponses avant la prochaine fenêtre planifiée.
4. GET /v1/monitors/{id}/analytics?days=30&engine=CHATGPT : lisez d’abord quality (comparable, lowSample, missingCells, partialDays), puis les chiffres. Interrogez jusqu’à ce que health.pending se stabilise et que quality.sampleSize cesse d’augmenter.
5. GET /v1/monitors/{id}/sources?days=30&groupBy=page : parcourez les pages avec nextCursor pour trouver celles qui remportent les prompts.
6. GET /v1/monitors/{id}/answers/{taskId} : ouvrez la réponse derrière la première entrée de opportunities avant de décider quoi que ce soit.
7. GET /v1/monitors/{id}/results?since=...&until=...&includeEvidence=true&format=csv : exportez la même fenêtre en suivant x-next-cursor jusqu’à ce qu’il soit vide.

​

Limites