Rankscale REST API
Rankscale 是一款 AI 品牌可见度跟踪工具。它会向各种 AI 模型（ChatGPT、Gemini、Claude、Perplexity 等）提示用户跟踪的搜索词，分析回复，并报告被跟踪品牌被提及的频率、位置以及正面程度。
此技能直接调用 REST API，以便用户（SEO 专业人员，而非开发人员）可以将数据拉入报告、图表和自定义分析中，而无需在仪表板上点击操作。
设置
- API 密钥：从环境变量
RANKSCALE_API_KEY中读取。密钥格式为rk_<hash>_<workspaceId>— 后缀是一个工作空间标识符，而非品牌 ID，因此一个密钥可以访问其工作空间中的每个品牌（特殊情况见 §15）。如果未设置，请要求用户设置一次：PowerShell 使用setx RANKSCALE_API_KEY "rk_..."（需要新 shell 才能生效），或在当前会话中通过$env:RANKSCALE_API_KEY = "rk_..."传递。切勿在回复中打印密钥或将其写入文件。 - 基础 URL：
https://rankscale.ai（注意：没有/api前缀 — 路径直接在营销域名上的/v1/...）。 - 认证头：
Authorization: Bearer $RANKSCALE_API_KEY。 - 速率限制：每个 API 密钥每分钟 200 个请求。响应会携带
X-RateLimit-Limit、X-RateLimit-Remaining和X-RateLimit-Reset（窗口重置前的秒数）— 如果进行批量工作，请使用curl -i读取它们。尽可能将报告响应缓存 5–10 分钟。 - 可用工具：用于请求的
curl。对于 JSON 解析，使用环境提供的任何工具 -node -e "..."、jq或python -m json.tool。在假设之前检查 PATH 上有什么；不要硬性依赖于其中任何一个。 - Shell 语法：下面的示例使用 bash 风格的变量展开（
$RANKSCALE_API_KEY）。在 Windows PowerShell 中，应将其替换为$env:RANKSCALE_API_KEY。选择您调用的任何 shell 工具 — 两者都可以，但要注意语法。
调用模式
每个端点成功时返回 {success: true, data: {...}}，失败时返回 {success: false, error: {code, message, details}}。在读取 .data 之前始终检查 .success。
也请检查 warnings。 一个成功的响应可能会携带第三个顶级键 warnings[]，列出 API 未识别并忽略的任何请求字段 — 通常带有“您是否是指”的建议（例如 “Ignored unrecognized field 'startDate'. Did you mean 'isoStartDate'? …”）。当请求是干净的时候，它就不存在，因此 if (json.warnings) 是一个可靠的防护。警告意味着得到的数据回答的问题与您提出的问题不同 — API 会为被丢弃的字段回退到默认值。应将其暴露给用户，而不是吞掉它；这是针对小驼峰命名陷阱（特殊情况 §1）最廉价的捕获方式。
将原始 JSON 响应保存到用户工作目录 adjacent 的文件中（通常为 Rankscale/<endpoint>_<context>.json），以便无需再次调用 API 即可重新分析。除非用户要求，否则向用户展示清晰的摘要，而不是原始 JSON。
令牌效率 — 最大的杠杆。 对于任何批量操作（多主题、多引擎、完整历史版本或带有 includeAnswerTexts 的 /search-terms-report），使用 -o 将响应直接写入磁盘，并使用 node -e 仅提取所需的值。不要将整个 /report 负载读入上下文 — 一个过滤后的报告大约 40–50 KB，一个 7 主题的扫描约为 300 KB。在客户端提取标量/序列可使它们脱离上下文，并且在批量拉取时，与内联读取负载相比，大约可以减少一半的令牌使用量。（对于单个窄指标，开销不值一提 — 只需读取小的响应即可。）
负载大小极其不均衡 — 请据此规划。 在单个品牌上测量：
| 端点 | 窗口 | 大小 |
|---|---|---|
/report（已过滤） | 30 天 | ~40–50 KB |
/report（已过滤） | 1 个日历月 | ~105–110 KB |
/citations | 3 个月 | ~3.9 MB |
/citations uncapped: true | 1 个日历月 | ~4.4–5.7 MB |
/sentiment | 30 天 | ~9 MB |
/sentiment | 3 个月 | ~17 MB |
大小不会随窗口长度线性增长 — uncapped: true 的影响要大得多。一个未设置上限的月份返回的数据大于一个设置了上限的三个月拉取的数据，因此不要从 3 个月那一行推断 1 个月的大小。
/sentiment 和 /citations 永远都不安全地内联读取 — 始终使用 -o 写入文件并提取。对于如此重的调用，也捕获 HTTP 状态（curl -w '%{http_code}'），因为一个瞬态的 502 可能会以一个看起来像是路径错误的 HTML 主体形式到达，但只需要重试即可（特殊情况 §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 等效命令
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
注意在 PowerShell 中：使用 curl.exe（别名 curl 指向的是 Invoke-WebRequest，其行为不同），在 -d JSON 主体中使用 \" 转义内部引号，并使用反引号 ` 续行。Invoke-RestMethod 也可以工作并且会自动解析 JSON，但 curl 形式能保持响应在不同 shell 间的一致性。
完整的端点清单和请求格式位于 references/endpoints.md 中。在不确定任何调用之前请阅读它。意外情况和陷阱位于 references/quirks.md 中 — 在向用户报告指标之前请阅读它，因为它们中的几个会影响数字的解释方式。
不在范围之内：共享链接 API。 Rankscale 发布了一个独立的 REST API 用于公共仪表板共享链接。它使用不同的密钥（设置 → 共享，而非设置 → 集成），因此 RANKSCALE_API_KEY 无法对其进行身份验证。如果用户要求创建或撤销共享链接，请说明这是一个独立的 API，此技能不涵盖 — 不要猜测其路径。
工作流模板
1. 识别品牌
大多数报告端点需要一个 brandId。当用户指定一个品牌（“显示 Acme 的指标”）时，请先解析其 ID：
- 如果
Rankscale/brands.json存在于用户的工作目录中，读取它。 - 否则调用
GET /v1/metrics/brands并保存结果。 - 将用户的品牌名称与
brands[].name（不区分大小写）以及与brands[].brandInfo.names（别名）进行匹配。如果找到多个匹配项，请要求用户澄清。
2. 按窗口拉取品牌指标
用户几乎总是会询问一个时间窗口。使用 timeFrame（小驼峰命名，大写 F — API 会静默忽略任何其他拼写），并使用以下记录在案的预设之一：24h、7d、30d、3m、1y。将其与 aggregation（hourly、daily、weekly 或 monthly）配对以指定时间桶大小。对于自定义窗口，使用 isoStartDate + isoEndDate（成对的 ISO 日期字符串）；这些会覆盖 timeFrame。
{
"brandId": "<id>",
"timeFrame": "30d",
"aggregation": "daily",
"includeNotFoundExecutions": true
}
可选的报告过滤器（所有过滤器都接受单个字符串、用于字段内“或”关系的数组，或用于无过滤的 "all"；过滤器在字段之间使用“与”关系组合）：
selectedTopic— 主题 ID、主题名称、_orphaned或数组selectedTags— 标签、__UNTAGGED__或数组selectedEngine— 引擎 ID（首选 — 参见references/endpoints.md获取目录）或友好名称selectedQuery— 确切的搜索词查询字符串或数组searchTermId— 单个搜索词 IDperiodOffset— 整数，将预设窗口向后移动 N 个周期（0 = 当前，1 = 上一个，...）userTimezone— IANA 时区，例如Europe/Berlin，用于基于用户本地时区划分日期边界includeNotFoundExecutions— 布尔值，控制“在回复中未找到品牌”的执行是否计入指标（参见 quirks.md）
从 data.ownBrandMetrics.historicalData.<aggregation>（例如，当您请求 aggregation: "daily" 时为 .daily）读取响应。每个桶数组 — visibilityScore、sentiment、mentions、sources、citations、citationCounts、avgPosition、detectionRate、top3、brandNotFound — 与 timestamps 并行对齐。
与之并排的三个并行时间序列：
data.ownBrandMetrics.topicMetricsData.<aggregation>— 按主题data.ownBrandMetrics.engineMetricsData.<aggregation>— 按引擎；上游未记录，通常是当窗口汇总看起来平缓时最有价值的切面，因为引擎级别的变动会在总计中相互抵消（特殊情况 §25）data.competitorTimeSeriesData.<aggregation>— 按竞争对手，不包括自有品牌（特殊情况 §16）
brandNotFound[] 是一个非信号 — 对于任何检测率低于 100% 的品牌，它几乎都读为 true。请改用 detectionRate，切勿使用该标志报告“未找到品牌”（特殊情况 §2）。
展示一个包含以下列的指标表：日期、可见度、情感、提及次数、引用次数、平均位置、检测率、Top-3 占比。在其上方，显示快照摘要（来自 ownBrandMetrics 的当前快照值 + trends 变化量）。
品牌排名（按可见度）— 与竞争对手对比。 根据 data.competitorMetrics[]（其中包括自有品牌，标记为 isOwnBrand: true）计算：排名 = 1 + (可见度得分严格更高的条目数量) — 并列不会降低品牌排名。这可以复现仪表板上的排名。响应中还为每个条目携带了 latestRank/avgRank — 这些不是排名。 2026-08-07 已验证：它们为一个计算排名为 1 的品牌返回非整数值（latestRank: 2.7，avgRank: 2.9），因此它们跟踪的是某种类似位置的东西，而非序数。请忽略它们。MCP 的等效 own_brand_rank 同样始终为 1（一个显示图钉）。上述按可见度排序的计算是在测试中与仪表板匹配的方法。共享过滤器（selectedEngine、selectedTopic、selectedTags、selectedQuery）按切面工作，因此您可以通过重新运行带过滤的请求来在单个引擎、主题、标签或查询内进行排名。注意 competitorMetrics 条目可能携带与自有品牌不同的 validMetricsCount（竞争对手基线使用更宽的窗口）— 排序仍然与 UI 匹配。完整模板 — 包括随时间变化的每日排名及其注意事项 — 请参见下面的模板 §6。
3. 引用分析
/v1/metrics/citations 返回 AI 模型在回答用户的搜索词时引用了哪些来源（网站、文章）。有助于理解哪些第三方域名会影响 AI 关于某个品牌的回答。
关键字段：data.totalCitations、data.uniqueCitations（不同的 URL）、data.uniqueDomains 和 data.citationsByDomain[]（每个域名）。在每个域名条目中，occurrences 是计数；citations 字段是 URL 的数组，而不是一个数字 — 因此引用份额 = occurrences / totalCitations，顶级 URL 来自展平每个域名的 URL 数组并按 occurrences 排序。
每个 URL 对象包含 {url, normalizedUrl, occurrences, engineAppearances: {<engineId>: count}, firstSeenAt, lastSeenAt, category, searchTerms[]}。engineAppearances 是 API 中唯一的按引擎的引用拆分 — 将其跨域名的 URL 求和可以回答“哪些引擎引用了我们的网站。” firstSeenAt/lastSeenAt 是您实际获得的窗口的唯一回显。在进行页面级分析之前，进一步对 normalizedUrl 进行规范化（它会保留 www./尾部斜杠/查询变体的差异），并注意 category: "owned" 意味着“公司自己的网站”，而不是被跟踪品牌 — 竞争对手也会携带它。参见 quirks.md §13b。data.domainSummary 有预定义的视图（topDomainsOverall、topDomainsByEngine、topDomainsByQuery、topDomainsByOwnBrandCitations、topDomainsByCompetitor）— 但这些视图有大小限制（≈20/10 个条目），并且 topDomainsByCompetitor 列出的是提及了竞争对手的域名（包括中立的第三方网站，如 Reddit/Booking），因此不要用它来识别竞争对手拥有的网站。参见 quirks.md §13b。
在调用列表完整之前检查上限。 响应默认限制为 5,000 个不同的 URL 和 50 个品牌。data.paginationInfo 报告了真实情况 — citationsCapped、brandsCapped、responseTrimmed、capBypassed、maxCitations、maxBrands、totalCount vs returnedCount。传递 uncapped: true（主体或查询参数）可以解除 URL 上限；它不会解除 50 个品牌的上限或响应大小保护。deduplicated: true 会对响应路径进行去重，并添加 data.searchTermsById。如果任何上限标志为 true，请告知用户并缩小窗口或应用过滤器，而不是将截断后的列表作为完整图像呈现。参见 quirks.md §13c。
4. 情感分析
/v1/metrics/sentiment 返回窗口级别的情感汇总以及关键词云，针对被跟踪品牌和每个竞争对手 — 不是一个时间序列（请使用 /report 的 historicalData.<agg>.sentiment[] 获取随时间变化的情感）。相同的共享过滤器，加上 deduplicated: true。
两个不同范围的数组：data.brandSentiments[] 仅包含被跟踪的品牌；data.companySentiments[] 包含每个检测到的品牌，包括自有品牌（isOwnBrand: true） — 对于竞争对手比较，请使用后者。brandSentimentsBySearchTerm[] / companySentimentsBySearchTerm[] 为每个搜索词提供相同的切面。
每个条目：avgSentiment（0–100 分制，= totalSentimentScore / sentimentCount）、sentimentCount、executionCount 以及 positiveCount / neutralCount / negativeCount。情感按来源拆分 — webGrounding*（基于网络的引擎）与 trainingData* 块，由 hasWebGrounding / hasTrainingData 布尔值分隔，其中 webGroundingSentimentByEngine[<engineId>] = {sum, count, avg} 提供按引擎的分数。
两个陷阱 — 在报告任何这些数据之前请阅读 quirks.md §19。 (1) p