Rankscale REST API
Rankscale 是一個 AI 品牌可見度追蹤工具。它會以使用者追蹤的搜尋字詞提示各種 AI 模型（ChatGPT、Gemini、Claude、Perplexity 等），分析回應，並報告追蹤品牌被提及的頻率、位置以及正面程度。
此技能直接呼叫 REST API，因此使用者（SEO 專業人士，而非開發者）無需點擊儀表板即可將資料提取到報告、圖表及自訂分析中。
設定
- API 金鑰：從環境變數
RANKSCALE_API_KEY讀取。金鑰格式為rk_<hash>_<workspaceId>— 後綴是工作區識別碼，而非品牌 ID，因此一個金鑰可存取其工作區中的每個品牌（怪癖 §15）。如果未設定，請要求使用者設定一次：PowerShellsetx RANKSCALE_API_KEY "rk_..."（需開啟新殼層才能生效），或透過$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 回應儲存到使用者工作目錄旁的檔案（通常是 Rankscale/<endpoint>_<context>.json），以便無需再次呼叫 API 即可重新分析。向使用者顯示乾淨的摘要，而不是原始 JSON，除非他們要求。
**令牌效率 — 最大的槓桿。**對於任何批量作業（多主題、多引擎、完整歷程，或帶有 includeAnswerTexts 的 /search-terms-report），使用 -o 將回應直接寫入磁碟，並使用 node -e 僅提取您需要的值。不要將整個 /report 有效負載讀入上下文 — 一個過濾後的報告約 40–50 KB，7 個主題的掃描約 300 KB。在用戶端提取純量/序列可使其脫離上下文，並且在批量拉取時，與內嵌讀取有效負載相比，約可節省一半的令牌使用量。（對於單一狹窄指標，開銷不值得 — 只需讀取小的回應即可。）
**有效負載大小極不均勻 — 請相應規劃。**在單一品牌上測量：
| 端點 | 時間範圍 | 大小 |
|---|---|---|
/report (過濾後) | 30d | ~40–50 KB |
/report (過濾後) | 1 個日曆月 | ~105–110 KB |
/citations | 3m | ~3.9 MB |
/citations uncapped: true | 1 個日曆月 | ~4.4–5.7 MB |
/sentiment | 30d | ~9 MB |
/sentiment | 3m | ~17 MB |
大小不會隨著時間範圍長度而縮放 — uncapped: true 的影響遠大得多。一個未設上限的月份資料回傳的大小比一個設上限的三個月拉取還要大，所以不要從 3m 那一行推斷 1m 的大小。
/sentiment 和 /citations 永遠不安全內嵌讀取 — 總是使用 -o 到檔案並提取。對於如此沉重的呼叫，也請捕獲 HTTP 狀態碼（curl -w '%{http_code}'），因為暫時性的 502 會以看起來像路徑錯誤的 HTML body 形式到達，但只需要重試即可（怪癖 §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 body 中的內部引號，並使用反引號 ` 進行行繼續。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
}
可選的報告過濾器（全部接受單一字串、陣列以進行欄位內 OR，或 "all" 表示不過濾；過濾器跨欄位以 AND 組合）：
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）。
呈現一個指標表格，包含以下欄位：日期、可見度、情緒、提及次數、引用次數、平均排名、檢測率 %、前 3 名 %。在其上方，顯示快照摘要（來自 ownBrandMetrics 的目前快照值 + trends 差異）。
**品牌排名（按可見度）— 與競爭者比較。**從 data.competitorMetrics[]（其中包含自身品牌，標記為 isOwnBrand: true）計算：排名 = 1 + (count of entries with strictly greater visibilityScore) — 平手不會使品牌排名下降。這可以重現儀表板的排名。回應也為每個條目攜帶 latestRank/avgRank — 這些不是排名。 已於 2026-08-07 驗證：對於計算排名為 1 的品牌，它們回傳非整數值（latestRank: 2.7、avgRank: 2.9），因此它們追蹤的是類似位置而非序數的內容。忽略它們。MCP 的等效 own_brand_rank 也始終是 1（顯示 pin）。上述的可見度排序計算是經過測試與儀表板匹配的方法。共享的過濾器（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（body 或 query 參數）以解除 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*（網路基礎的引擎）vs trainingData* 區塊，由 hasWebGrounding / hasTrainingData 布林值控制，並附帶 webGroundingSentimentByEngine[<engineId>] = {sum, count, avg} 以取得每個引擎的分數。
兩個陷阱 — 在報告任何這些之前，請閱讀 quirks.md §19。 (1) `p
…
[為翻譯而截斷]