GEO-Monitoring-API: Markennennungen und Quellenangaben

​

Was ein Monitor ist

• Sie hält fest, ob ein Marken-Alias im Antworttext vorkommt und an welchem Zeichen-Offset, ob die Antwort eine Ihrer registrierten Domains zitiert hat und welche Ihrer konfigurierten Wettbewerber in derselben Antwort vorkamen.
• Sie erzeugt keinen Sentiment-Wert und keine geschätzte Marktanteilszahl. Ein Rang ist ein Platz unter den Marken, die die Antworten nennen, wie im Ranking eines Kategorie-Monitors (siehe unten).

​

Wettbewerber werden für Sie gefunden

• Gefundene Wettbewerber tragen source: "auto". Selbst hinzugefügte tragen source: "user" und werden beim Lesen nie geändert oder entfernt.
• Ändert sich die gefundene Liste, werden die gespeicherten Antworten des Monitors neu dagegen gezählt, damit jede Marke eines Berichts über dieselben Antworten gemessen wird. competitorsReadAt am Monitor zeigt den letzten Lauf.
• Namen in lateinischer Schrift werden als ganze Wörter erkannt, „replicates“ ist also keine Nennung der Marke Replicate.

​

Monitor-Sets bewusst aufteilen

• Ein Monitor pro Thema und Markt, damit die Kohorte eines Berichts vergleichbar bleibt. Wer „bestes CRM“ und „wie bepreist man ein CRM“ in ein Prompt-Set mischt, mittelt zwei verschiedene Absichten zu einer Zahl.
• Formulieren Sie Prompts wie ein Käufer und nehmen Sie nie Ihre eigene Marke auf. Ein Prompt mit der Marke ist immer eine Nennung, meldet also für immer 100 % und misst nichts. Wettbewerbernamen sind in Ordnung und oft die nützlichsten Prompts, die Sie schreiben können.

​

Kategorie-Monitore: die Marken eines Marktes ranken

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
  }'

​

Was der Bericht rankt

• rank ordnet Marken nach der Zahl der Antworten, die sie nennen: Er ist ein Platz unter den Marken, die diese Antworten nennen. Eine Marke, die keine Antwort genannt hat, hat rank: null.
• Die mentionRate einer Marke teilt durch ihre eigene sampleSize, die Antworten, die bewertet wurden, während die Marke auf der Liste stand. Eine Marke, die Sie heute hinzufügen, wird ab heute gemessen.
• shareOfVoice ist 100 × Nennungen dieser Marke / alle Nennungen verfolgter Marken im Fenster, die Anteile eines Fensters summieren sich also auf 100.
• GET /v1/monitors ergänzt bei jedem Kategorie-Monitor leader (die am häufigsten genannte Marke mit ihrer Rate). Seine Zähler mentioned und cited sind immer 0.
• GET /v1/monitors/{id}/answers/{taskId} liefert mode, ein leeres aliases und die verfolgten Marken als competitors.

​

Prompts aus der Suchnachfrage recherchieren

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"] }'

​

Kosten und Zeitplan

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

• Ein Lauf ist kein Burst. Tasks werden zugelassen, soweit Tarif-Parallelität und Warteschlange es erlauben. Ein Lauf über dem Limit eines Gratis-Tarifs trifft daher über mehrere Minuten ein, statt verworfen zu werden. Beobachten Sie health.pending in einem Bericht, um einen laufenden Durchgang zu sehen.
• Das nächste Fenster ist ein Zeitpunkt, keine Garantie. nextRunAt ist der Fälligkeitszeitpunkt. Ein eine Woche lang pausierter Monitor läuft ein Intervall nach der Reaktivierung weiter, statt die verpassten Läufe nachzuholen.

​

Endpunkte

​

Einen Monitor anlegen

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
  }'

​

Ausführen, dann den Bericht lesen

​

Was die Zahlen bedeuten

• mentionRate für das Fenster, seine Engine-Gruppen und seine Zell-Gruppen ist 100 × Antworten mit Nennung / bewertete Antworten. Sie ist nach Antworten gewichtet, kein Mittelwert der Engine-Quoten, sodass eine vielgenutzte Engine nicht von einer wenig genutzten überstimmt wird. (Die eigene Quote einer Marke hat einen eigenen Nenner, siehe nächster Punkt.)
• citationRate hat dieselbe Form für Antworten, die eine Ihrer registrierten Domains zitiert haben. Ohne registrierte Domains ist sie immer null, weil die Quellenverfolgung aus ist.
• Die Quote einer Marke teilt durch ihre eigene sampleSize, nicht durch die Fenstersumme. Für Ihre Marke sind das alle bewerteten Antworten; für einen Wettbewerber nur die Antworten, die bewertet wurden, während er im Monitor war. Fügen Sie heute einen Wettbewerber hinzu, deckt sein erster Bericht die Antworten ab, die ihn gemessen haben: Die Zeit vor seiner Aufnahme zählt nicht gegen ihn. Eine Marke ohne passende Antworten meldet mentionRate: null, nicht 0 %, weil 0 % wie ein echtes Verschwinden wirken würde.
• shareOfVoice in brands ist 100 × Nennungen dieser Marke / alle Nennungen beobachteter Marken im Fenster, die Anteile eines Fensters ergeben also zusammen 100. Es vergleicht Marken innerhalb der Antworten, die Sie für diese Prompts gesammelt haben; es ist weder Marktanteil noch Sichtbarkeitsranking. Das shareOfVoice des veralteten Detail-Endpunkts ist die ältere Sicht der Antwortdurchdringung, bei der jede Marke gegen die gesammelten Antworten gezählt wird und die Summe über 100 liegen kann. Mischen Sie beides nicht in einem Diagramm.
• competitorOnly (und die Liste opportunities) zählt Antworten, die einen konfigurierten Wettbewerber nannten, während Ihre Marke fehlte. Das ist die Lücke, an der Sie ansetzen können.
• Quoten sind nullbar, nicht null. Keine Antworten im Fenster ergibt null; eine Quote von null bedeutet, dass es Antworten gab und keine passte.
• Eine abgeschlossene Beobachtung ohne Antwort zählt als nicht genannt. Sie bleibt im Nenner, und quality.noAnswerObservations gibt an, wie viele es waren. Ein fehlgeschlagener Task wird aus allen Quoten ausgeschlossen und erscheint nur in health. Eine defekte Engine verkleinert die Stichprobe, statt stillschweigend zu einer Abwesenheit zu werden, und quality rekonstruiert sie nie als solche (historicalFailures ist immer null).
• Veränderungen werden zurückgehalten, wenn sie irreführen würden. changes und das mentionRateChangePp pro Zelle sind null, und quality.comparable ist false, wenn eine Periode keine Antworten hat (insufficient_periods), wenn Zeilen bewertet wurden, bevor es einen Bewertungskontext gab (legacy_scoring_unknown), oder wenn sich die Bewertungsdefinition zwischen den Perioden geändert hat (scoring_definitions_changed). Historische Zeilen behalten die Definitionen, mit denen sie bewertet wurden (quality.scoring). Änderungen an Aliasen oder Wettbewerbern schreiben die Vergangenheit also nie um. Einzige Ausnahme ist das oben beschriebene monatliche Lesen der Wettbewerber.
• Die Stichprobengröße wird veröffentlicht. quality.lowSample ist unter 30 bewerteten Antworten true, quality.missingCells zählt konfigurierte Prompt × Engine-Zellen ohne bisherige Antworten, und quality.partialDays nennt die UTC-Tage, die das Fenster halbiert. Der niedrigere Zählwert eines Teiltags ist Arithmetik, kein Rückgang.

​

Woher die Antworten kommen

​

Zitationen im Zeitverlauf

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

​

Die bewerteten Zeilen exportieren

​

Die Antwort hinter einer Zahl lesen

• answerText: die Antwort, wie die Engine sie gegeben hat, wenn möglich als Markdown, höchstens 8.000 Zeichen, bei größerer Länge mit Auslassungszeichen gekürzt.
• sources: die Quellenangaben in der Reihenfolge der Engine, jeweils mit Label und 1-basierter Position in dieser Liste.
• aliases und competitors: womit diese Zeile abgeglichen wurde, damit die Nennung geprüft statt einfach geglaubt werden kann.
• scoringContext: die exakt verwendete Definition, mit version-Hash, Bewertungszeit, answerPresent und evidenceTruncated, wenn der Text oben gekürzt wurde.

​

Fehler auf dieser Oberfläche

​

Ein Agent im Ablauf

1. GET /v1/monitors/capabilities: Engines, Preise und Limits lesen, bevor etwas ausgegeben wird.
2. GET /v1/monitors: einen vorhandenen Monitor für Thema und Markt wiederverwenden oder mit POST /v1/monitors einen anlegen (optional zuerst POST /v1/monitors/suggest aufrufen und die Vorschläge bearbeiten).
3. POST /v1/monitors/{id}/run: falls Sie Antworten vor dem nächsten geplanten Fenster brauchen.
4. GET /v1/monitors/{id}/analytics?days=30&engine=CHATGPT: zuerst quality lesen (comparable, lowSample, missingCells, partialDays), dann die Zahlen. Pollen, bis health.pending sich beruhigt und quality.sampleSize nicht mehr wächst.
5. GET /v1/monitors/{id}/sources?days=30&groupBy=page: mit nextCursor blättern, um die Seiten zu finden, die die Prompts gewinnen.
6. GET /v1/monitors/{id}/answers/{taskId}: die Antwort hinter dem obersten Eintrag in opportunities öffnen, bevor etwas entschieden wird.
7. GET /v1/monitors/{id}/results?since=...&until=...&includeEvidence=true&format=csv: dasselbe Fenster exportieren und x-next-cursor folgen, bis er leer ist.

​

Limits