Rankscale REST-API
Rankscale ist ein Tool zur Verfolgung der KI-Markensichtbarkeit. Es fordert verschiedene KI-Modelle (ChatGPT, Gemini, Claude, Perplexity usw.) mit den vom Benutzer überwachten Suchbegriffen auf, analysiert die Antworten und berichtet, wie oft, wo und wie positiv die verfolgten Marken erwähnt werden.
Dieser Skill ruft die REST-API direkt auf, damit der Benutzer (ein SEO-Experte, kein Entwickler) Daten in Berichte, Diagramme und benutzerdefinierte Analysen einfließen lassen kann, ohne durch das Dashboard klicken zu müssen.
Einrichtung
- API-Schlüssel: Wird aus der Umgebungsvariablen
RANKSCALE_API_KEYgelesen. Das Schlüsselformat istrk_<hash>_<workspaceId>– das Suffix ist eine Workspace-Kennung, keine Marken-ID. Ein Schlüssel erreicht also jede Marke in seinem Workspace (siehe Eigenheiten §15). Falls nicht gesetzt, bitten Sie den Benutzer, ihn einmalig zu setzen: PowerShellsetx RANKSCALE_API_KEY "rk_..."(ein neues Shell-Fenster ist erforderlich, damit die Änderung wirksam wird) oder übergeben Sie ihn sitzungsweise mit$env:RANKSCALE_API_KEY = "rk_...". Geben Sie den Schlüssel niemals in Antworten aus oder schreiben Sie ihn in Dateien. - Basis-URL:
https://rankscale.ai(Hinweis: kein/api-Präfix – der Pfad ist/v1/...direkt auf der Marketing-Domain). - Auth-Header:
Authorization: Bearer $RANKSCALE_API_KEY. - Ratenbegrenzung: 200 Anfragen pro Minute pro API-Schlüssel. Die Antwort enthält
X-RateLimit-Limit,X-RateLimit-RemainingundX-RateLimit-Reset(Sekunden bis zum Reset des Fensters) – lesen Sie diese mitcurl -i, wenn Sie Batch-Arbeiten durchführen. Zwischenspeichern Sie Antworten von Berichten wenn möglich für 5–10 Minuten. - Verfügbare Tools:
curlfür Anfragen. Verwenden Sie für die JSON-Parsing, was auch immer die Umgebung bietet –node -e "...",jqoderpython -m json.tool. Überprüfen Sie, was im PATH ist, bevor Sie Annahmen treffen; machen Sie sich nicht von einem einzelnen Tool abhängig. - Shell-Syntax: Die folgenden Beispiele verwenden bash-artige Variablenexpansion (
$RANKSCALE_API_KEY). In Windows PowerShell wird daraus$env:RANKSCALE_API_KEY. Wählen Sie das Shell-Tool, das Sie aufrufen – beide funktionieren, aber achten Sie auf die Syntax.
Aufrufmuster
Jeder Endpunkt gibt bei Erfolg {success: true, data: {...}} oder bei Fehlschlag {success: false, error: {code, message, details}} zurück. Überprüfen Sie immer .success, bevor Sie .data lesen.
Überprüfen Sie auch warnings. Eine erfolgreiche Antwort kann einen dritten Schlüssel auf oberster Ebene enthalten, warnings[], in dem alle Anfragefelder aufgelistet werden, die die API nicht erkannt und ignoriert hat – oft mit einem „Meinten Sie" ("Ignored unrecognized field 'startDate'. Did you mean 'isoStartDate'? …"). Er fehlt, wenn die Anfrage sauber war, daher ist if (json.warnings) eine zuverlässige Prüfung. Eine Warnung bedeutet, dass die Zahlen eine andere Frage beantworten als die gestellte – die API verwendet für das verworfene Feld Standardwerte. Machen Sie den Benutzer darauf aufmerksam, anstatt sie zu verschlucken; dies ist der billigste mögliche Fang für die camelCase-Falle (siehe Eigenheiten §1).
Speichern Sie rohe JSON-Antworten in einer Datei neben der Arbeit des Benutzers (normalerweise Rankscale/<Endpunkt>_<Kontext>.json), damit sie ohne erneuten API-Aufruf neu analysiert werden können. Zeigen Sie dem Benutzer eine saubere Zusammenfassung, kein rohes JSON, es sei denn, er fragt danach.
Token-Effizienz – der größte Hebel. Für alles, was Bulk ist (Multi-Thema, Multi-Engine, vollständiger Verlauf oder /search-terms-report mit includeAnswerTexts), schreiben Sie die Antwort mit -o direkt auf die Festplatte und extrahieren Sie nur die benötigten Werte mit node -e. Lesen Sie nicht ganze /report-Payloads in den Kontext – ein gefilterter Bericht hat etwa 40–50 KB und eine 7-Themen-Erfassung etwa 300 KB. Das clientseitige Extrahieren von Skalaren/Serien hält sie außerhalb des Kontexts und halbiert bei Bulk-Abzügen grob den Tokenverbrauch im Vergleich zum Inline-Lesen von Payloads. (Für eine einzelne enge Metrik ist der Aufwand nicht lohnenswert – lesen Sie einfach die kleine Antwort.)
Payload-Größen sind extrem ungleichmäßig – planen Sie entsprechend. Gemessen an einer einzelnen Marke:
| Endpunkt | Fenster | Größe |
|---|---|---|
/report (gefiltert) | 30d | ~40–50 KB |
/report (gefiltert) | 1 Kalendermonat | ~105–110 KB |
/citations | 3m | ~3,9 MB |
/citations uncapped: true | 1 Kalendermonat | ~4,4–5,7 MB |
/sentiment | 30d | ~9 MB |
/sentiment | 3m | ~17 MB |
Die Größe skaliert nicht mit der Fensterlänge – uncapped: true hat weitaus mehr Einfluss. Ein einzelner unbegrenzter Monat kam größer zurück als ein begrenzter Drei-Monats-Abruf, also extrapolieren Sie nicht von der Größe des 3m-Eintrags auf die Größe eines 1-Monats-Fensters.
/sentiment und /citations sind niemals sicher inline zu lesen – immer -o in eine Datei und extrahieren. Erfassen Sie bei solch schweren Aufrufen auch den HTTP-Status (curl -w '%{http_code}'), denn ein vorübergehender 502 kommt als HTML-Body an, der wie ein defekter Pfad aussieht, aber nur einen erneuten Versuch benötigt (Eigenheiten §6).
# Bash (Git Bash / WSL / macOS / Linux)
curl -s -H "Authorization: Bearer $RANKSCALE_API_KEY" \
"https://rankscale.ai/v1/metrics/brands" \
-o brands.json
curl -s -X POST -H "Authorization: Bearer $RANKSCALE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"brandId":"<id>"}' \
"https://rankscale.ai/v1/metrics/report" \
-o report.json
# PowerShell-Äquivalent
curl.exe -s -H "Authorization: Bearer $env:RANKSCALE_API_KEY" `
"https://rankscale.ai/v1/metrics/brands" `
-o brands.json
curl.exe -s -X POST -H "Authorization: Bearer $env:RANKSCALE_API_KEY" `
-H "Content-Type: application/json" `
-d '{\"brandId\":\"<id>\"}' `
"https://rankscale.ai/v1/metrics/report" `
-o report.json
Beachten Sie in PowerShell: Verwenden Sie curl.exe (der Alias curl zeigt auf Invoke-WebRequest, das sich anders verhält), maskieren Sie innere Anführungszeichen in -d JSON-Bodies mit \" und verwenden Sie das Backtick ` für Zeilenumbrüche. Invoke-RestMethod funktioniert auch und parst JSON automatisch, aber die curl-Form hält die Antworten über alle Shells hinweg konsistent.
Das vollständige Endpunkt-Inventar und die Anfrageformate finden Sie in references/endpoints.md. Lesen Sie es vor jedem Aufruf, bei dem Sie sich nicht sicher sind. Überraschungen und Fallstricke finden Sie in references/quirks.md – lesen Sie es, bevor Sie Metriken an den Benutzer melden, da mehrere von ihnen die Interpretation der Zahlen beeinflussen.
Nicht im Umfang enthalten: die Share-Links-API. Rankscale veröffentlicht eine zweite REST-API für öffentliche Dashboard-Freigabelinks. Sie verwendet einen anderen Schlüssel (Einstellungen → Freigabe, nicht Einstellungen → Integrationen), daher wird RANKSCALE_API_KEY sich nicht dagegen authentifizieren können. Wenn der Benutzer fragt, ob ein Freigabelink erstellt oder widerrufen werden soll, sagen Sie, dass dies eine separate API ist, die dieser Skill nicht abdeckt – raten Sie nicht über ihre Pfade.
Workflow-Rezepte
1. Die Marke identifizieren
Die meisten Berichts-Endpunkte benötigen eine brandId. Wenn der Benutzer eine Marke nennt („Zeig mir die Metriken von Acme"), lösen Sie die ID zuerst auf:
- Wenn
Rankscale/brands.jsonim Arbeitsverzeichnis des Benutzers existiert, lesen Sie es. - Andernfalls rufen Sie
GET /v1/metrics/brandsauf und speichern das Ergebnis. - Gleichen Sie den Markennamen des Benutzers mit
brands[].name(Groß-/Kleinschreibung wird ignoriert) und mitbrands[].brandInfo.names(Aliase) ab. Bei mehreren Übereinstimmungen bitten Sie den Benutzer, die genaue Marke zu wählen.
2. Metriken für eine Marke über ein Fenster abrufen
Der Benutzer fragt fast immer nach einem Zeitfenster. Verwenden Sie timeFrame (camelCase, großes F – die API ignoriert jede andere Schreibweise stillschweigend) mit einem dieser dokumentierten Presets: 24h, 7d, 30d, 3m, 1y. Kombinieren Sie es mit aggregation (hourly, daily, weekly oder monthly) für die Intervallgröße. Für benutzerdefinierte Fenster verwenden Sie isoStartDate + isoEndDate (gepaarte ISO-Datumsstrings); diese überschreiben timeFrame.
{
"brandId": "<id>",
"timeFrame": "30d",
"aggregation": "daily",
"includeNotFoundExecutions": true
}
Optionale Berichtsfilter (alle akzeptieren einen einzelnen String, ein Array für ODER-innerhalb-des-Feldes oder "all" für keinen Filter; Filter werden UND-verknüpft über alle Felder hinweg):
selectedTopic– Themen-ID, Themenname,_orphanedoder ArrayselectedTags– Tag,__UNTAGGED__oder ArrayselectedEngine– Engine-ID (bevorzugt – siehereferences/endpoints.mdfür den Katalog) oder AnzeigenameselectedQuery– exakter Suchbegriffs-Query-String oder ArraysearchTermId– einzelne Suchbegriffs-IDperiodOffset– Integer, verschiebt das Preset-Fenster um N Perioden zurück (0 = aktuell, 1 = vorherig, …)userTimezone– IANA-Zeitzone wieEurope/Berlinfür benutzerlokale TagesgrenzenincludeNotFoundExecutions– Boolean, steuert, ob die Ausführungen mit „Marke nicht in der Antwort gefunden" in die Metriken einfließen (siehe quirks.md)
Lesen Sie die Antwort aus data.ownBrandMetrics.historicalData.<aggregation> (z.B. .daily wenn Sie nach aggregation: "daily" gefragt haben). Jedes Bucket-Array – visibilityScore, sentiment, mentions, sources, citations, citationCounts, avgPosition, detectionRate, top3, brandNotFound – verläuft parallel zu timestamps.
Drei parallele Zeitreihen befinden sich daneben:
data.ownBrandMetrics.topicMetricsData.<aggregation>– pro Themadata.ownBrandMetrics.engineMetricsData.<aggregation>– pro Engine; vorgelagert undokumentiert und normalerweise der wertvollste Schnitt, wenn ein Fenster-Durchschnitt flach aussieht, weil sich Engine-Ebene-Bewegungen in der Summe gegenseitig aufheben (Eigenheiten §25)data.competitorTimeSeriesData.<aggregation>– pro Wettbewerber, eigene Marke ausgeschlossen (Eigenheiten §16)
brandNotFound[] ist ein Nicht-Signal – es steht bei true für praktisch jede Marke mit einer Erkennungsrate unter 100%. Verwenden Sie stattdessen detectionRate und melden Sie „Marke nicht gefunden" niemals auf Basis des Flags (Eigenheiten §2).
Präsentieren Sie eine Metrikentabelle mit diesen Spalten: Datum, Sichtbarkeit, Stimmung, Erwähnungen, Zitate, Durchschnittl. Position, Erkennungsrate %, Top-3-%. Darüber zeigen Sie die Momentaufnahme-Zusammenfassung (aktuelle Momentaufnahme-Werte aus ownBrandMetrics + das trends-Delta).
Markenrang (nach Sichtbarkeit) – vs. Wettbewerber. Berechnen Sie dies aus data.competitorMetrics[] (das die eigene Marke enthält, gekennzeichnet mit isOwnBrand: true): Rang = 1 + (Anzahl der Einträge mit strikt größerem visibilityScore) – Gleichstände drücken die Marke nicht nach unten. Dies reproduziert den Rang des Dashboards. Die Antwort enthält auch latestRank/avgRank pro Eintrag – dies sind keine Ränge. Verifiziert am 2026-08-07: Sie geben nicht-ganzzahlige Werte zurück (latestRank: 2.7, avgRank: 2.9) für eine Marke, deren berechneter Rang 1 war, also messen sie etwas Positionsähnliches, keinen Ordinalwert. Ignorieren Sie sie. Das entsprechende own_brand_rank des MCP ist ebenfalls immer 1 (ein Anzeige-Pin). Die oben beschriebene, nach Sichtbarkeit sortierte Berechnung ist die Methode, die im Test mit dem Dashboard übereinstimmte. Die gemeinsamen Filter (selectedEngine, selectedTopic, selectedTags, selectedQuery) funktionieren pro Schnitt, sodass Sie innerhalb einer einzelnen Engine, eines Themas, Tags oder Queries durch erneutes Ausführen mit Filter ranken können. Beachten Sie, dass competitorMetrics-Einträge eine andere validMetricsCount haben können als die eigene Marke (Wettbewerber-Baselines verwenden ein breiteres Fenster) – die Sortierung stimmt dennoch mit der UI überein. Das vollständige Rezept – einschließlich des täglichen Rangs über die Zeit und seiner Einschränkungen – finden Sie in Rezept §6 unten.
3. Zitatanalysen
/v1/metrics/citations gibt zurück, welche Quellen (Websites, Artikel) KI-Modelle bei der Beantwortung der Suchbegriffe des Benutzers zitieren. Nützlich, um zu verstehen, welche Drittanbieter-Domains die KI-Antworten über eine Marke beeinflussen.
Wichtige Felder: data.totalCitations, data.uniqueCitations (unterschiedliche URLs), data.uniqueDomains und data.citationsByDomain[] (jede Domain). In jedem Domain-Eintrag ist occurrences die Anzahl; das Feld citations ist das Array der URLs, keine Zahl – der Zitieranteil ist also = occurrences / totalCitations, und die wichtigsten URLs ergeben sich aus dem Flatten des URL-Arrays jeder Domain und dem Sortieren nach occurrences.
Jedes URL-Objekt ist {url, normalizedUrl, occurrences, engineAppearances: {<engineId>: count}, firstSeenAt, lastSeenAt, category, searchTerms[]}. engineAppearances ist die einzige pro-Engine-Zitataufschlüsselung in der API – summieren Sie es über die URLs einer Domain, um die Frage zu beantworten: „Welche Engines zitieren unsere Website?" firstSeenAt/lastSeenAt sind das einzige Echo des tatsächlich erhaltenen Fensters. Normalisieren Sie normalizedUrl vor einer Seitenebenen-Analyse weiter (es belässt www./trailing-Slash/Query-Varianten unterschiedlich), und beachten Sie, dass category: "owned" bedeutet: „Die eigene Website eines Unternehmens", nicht die der verfolgten Marke – Wettbewerber tragen es ebenfalls. Siehe quirks.md §13b. data.domainSummary hat vorgefertigte Ansichten (topDomainsOverall, topDomainsByEngine, topDomainsByQuery, topDomainsByOwnBrandCitations, topDomainsByCompetitor) – diese sind jedoch begrenzt (≈20/10 Einträge) und topDomainsByCompetitor listet Domains, in denen ein Wettbewerber erwähnt wurde (enthält neutrale Drittanbieter-Seiten wie Reddit/Booking), daher nicht verwenden, um Wettbewerber-eigene Websites zu identifizieren. Siehe quirks.md §13b.
Überprüfen Sie die Begrenzungen, bevor Sie eine Liste als vollständig bezeichnen. Die Antwort begrenzt standardmäßig auf 5.000 eindeutige URLs und 50 Marken. data.paginationInfo meldet die Wahrheit – citationsCapped, brandsCapped, responseTrimmed, capBypassed, maxCitations, maxBrands, totalCount vs returnedCount. Übergeben Sie uncapped: true (Body- oder Query-Parameter), um die URL-Begrenzung aufzuheben; es hebt nicht die 50-Marken-Begrenzung oder die Antwortgrößen-Begrenzung auf. deduplicated: true dedupliziert Antwortpfade und fügt data.searchTermsById hinzu. Wenn eines der Cap-Flags true ist, teilen Sie dies dem Benutzer mit und verkleinern Sie das Fenster oder filtern Sie, anstatt eine abgeschnittene Liste als vollständiges Bild darzustellen. Siehe quirks.md §13c.
4. Stimmungsanalyse
/v1/metrics/sentiment gibt Stimmungsaggregate auf Fensterebene plus Keyword-Wolken für die verfolgte Marke und jeden Wettbewerber zurück – keine Zeitreihe (verwenden Sie für Stimmung im Zeitverlauf /report's historicalData.<agg>.sentiment[]). Gleiche gemeinsame Filter, plus deduplicated: true.
Zwei Arrays mit unterschiedlichen Umfängen: data.brandSentiments[] ist nur die verfolgte Marke; data.companySentiments[] ist jede erkannte Marke einschließlich der eigenen Marke (isOwnBrand: true) – verwenden Sie dieses für Wettbewerbsvergleiche. brandSentimentsBySearchTerm[] / companySentimentsBySearchTerm[] liefern die gleichen Schnitte pro Suchbegriff.
Pro Eintrag: avgSentiment (Skala 0–100, = totalSentimentScore / sentimentCount), sentimentCount, executionCount und positiveCount / neutralCount / negativeCount. Die Stimmung wird nach Quelle aufgeteilt – webGrounding*-(webgestützte Engines) vs. trainingData*-Blöcke, gesteuert durch die booleschen Werte hasWebGrounding / hasTrainingData, mit webGroundingSentimentByEngine[<engineId>] = {sum, count, avg} für Pro-Engine-Werte.
Zwei Fallstricke – lesen Sie quirks.md §19, bevor Sie dies melden. (1) p
[... für die Übersetzung gekürzt]