bojan-basrak/rankscale-api-skill

Rankscale REST API

Rankscaleは、AIブランド認知度トラッキングツールです。ユーザーが追跡している検索語句を様々なAIモデル（ChatGPT、Gemini、Claude、Perplexityなど）にプロンプトし、その応答を分析して、追跡されているブランドがどの程度、どこで、どの程度好意的に言及されているかをレポートします。

このスキルはREST APIを直接呼び出すため、ユーザー（開発者ではないSEOプロフェッショナル）は、ダッシュボードをクリックしなくても、レポート、チャート、カスタム分析にデータを取り込むことができます。

セットアップ

• APIキー: 環境変数RANKSCALE_API_KEYから読み取ります。キーの形式はrk_<ハッシュ>_<ワークスペースID>です。サフィックスはワークスペース識別子であり、ブランドIDではありません。そのため、1つのキーでワークスペース内のすべてのブランドにアクセスできます（quirks §15）。設定されていない場合は、ユーザーに一度設定するよう依頼してください。PowerShell: setx RANKSCALE_API_KEY "rk_..."（反映には新しいシェルが必要）、またはセッションごとに$env:RANKSCALE_API_KEY = "rk_..."で渡します。応答内でキーを表示したり、ファイルに書き込んだりしないでください。
• ベースURL: https://rankscale.ai（注意: /apiプレフィックスはありません。パスはマーケティングドメイン上で直接/v1/...となります）。
• 認証ヘッダー: Authorization: Bearer $RANKSCALE_API_KEY。
• レート制限: APIキーあたり1分間に200リクエスト。レスポンスにはX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（ウィンドウがリセットされるまでの秒数）が含まれます。バッチ処理を行う場合はcurl -iでこれらを読み取ってください。可能であれば、レポート応答は5〜10分間キャッシュしてください。
• 利用可能なツール: リクエストにはcurlを使用します。JSONパースには、環境が提供するもの（node -e "..."、jq、python -m json.tool）を使用してください。PATHに何があるかを事前に確認し、特定のツールに依存しないようにしてください。
• シェル構文: 以下の例ではbash形式の変数展開（$RANKSCALE_API_KEY）を使用しています。Windows PowerShellでは$env:RANKSCALE_API_KEYになります。呼び出すシェルツールに応じて適切な方を選択してください。どちらも動作しますが、構文に注意してください。

呼び出しパターン

すべてのエンドポイントは、成功時には{success: true, data: {...}}を、失敗時には{success: false, error: {code, message, details}}を返します。.dataを読み取る前に、常に.successを確認してください。

warningsも確認してください。 成功応答には、3つ目のトップレベルキーとしてwarnings[]が含まれる場合があります。これは、APIが認識せず無視したリクエストフィールドをリストし、多くの場合「もしかして：」を含みます（"Ignored unrecognized field 'startDate'. Did you mean 'isoStartDate'? ..."）。リクエストが正常な場合はこのフィールドは存在しないため、if (json.warnings)は信頼できるガードです。警告は、数字が意図したものとは異なる質問に答えていることを意味します — APIはドロップされたフィールドのデフォルト値にフォールバックします。警告を無視せずにユーザーに提示してください。これは、camelCaseの罠をキャッチするための最も簡単な方法です（quirks §1）。

生のJSON応答は、ユーザーの作業ファイルの隣（通常はRankscale/<エンドポイント>_<コンテキスト>.json）に保存し、APIを再度呼び出さなくても再分析できるようにしてください。ユーザーが特に要求しない限り、生のJSONではなく、クリーンなサマリーを表示してください。

トークン効率 — 最大のレバレッジポイント。 バルク処理（マルチトピック、マルチエンジン、全履歴、またはincludeAnswerTextsを使用した/search-terms-report）の場合は、-oを使用して応答を直接ディスクに書き込み、node -eを使用して必要な値のみを抽出してください。/reportペイロード全体をコンテキストに読み込まないでください — フィルタリングされた1つのレポートは約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の方がはるかに重要です。キャップなしの1ヶ月分は、キャップ付きの3ヶ月分よりも大きくなる可能性があるため、3ヶ月の行から1ヶ月のサイズを推定しないでください。

/sentimentと/citationsはインラインで読み取っても安全ではありません — 常に-oでファイルに保存してから抽出してください。このような重い呼び出しでは、HTTPステータスもキャプチャしてください（curl -w '%{http_code}'）。なぜなら、一時的な502が、壊れたパスのように見えるHTML本文として到着する可能性があるからです。これは単にリトライが必要なだけです（quirks §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を指しており、動作が異なります）。JSON本文の-d内の引用符をエスケープするには\"を使用し、行継続にはバックティック`を使用してください。Invoke-RestMethodも機能し、JSONを自動解析しますが、curl形式を使用すると、シェル間で応答を一貫させることができます。

完全なエンドポイント一覧とリクエストの形状はreferences/endpoints.mdにあります。不明な呼び出しを行う前には、必ずそれを読んでください。驚きや落とし穴はreferences/quirks.mdにあります — ユーザーにメトリクスを報告する前に読んでください。これらのいくつかは、数値の解釈方法に影響を与えるためです。

対象外：共有リンクAPI。 Rankscaleは、公開ダッシュボード共有リンク用に別のREST APIを公開しています。これは異なるキー（Settings → Sharing、Settings → Integrationsではない）を使用するため、RANKSCALE_API_KEYでは認証されません。ユーザーが共有リンクの作成や取り消しを要求した場合は、このスキルではカバーされていない別のAPIであることを伝えてください — そのパスを推測しないでください。

ワークフローレシピ

1. ブランドの特定

ほとんどのレポートエンドポイントにはbrandIdが必要です。ユーザーがブランドを指定した場合（「Acmeのメトリクスを見せて」）、最初にIDを解決します。

1. ユーザーの作業ディレクトリにRankscale/brands.jsonが存在する場合は、それを読み取ります。
2. 存在しない場合は、GET /v1/metrics/brandsを呼び出し、結果を保存します。
3. ユーザーのブランド名をbrands[].name（大文字小文字を区別しない）およびbrands[].brandInfo.names（エイリアス）と照合します。複数の一致がある場合は、ユーザーに識別を依頼します。

2. 時間枠に対するブランドのメトリクスを取得する

ユーザーはほとんどの場合、時間枠を指定します。timeFrame（camelCase、大文字の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-within-fieldの配列、またはフィルターなしの"all"を受け入れます。フィルターはフィールド間でANDで結合されます）：

• selectedTopic — トピックID、トピック名、_orphaned、または配列
• selectedTags — タグ、__UNTAGGED__、または配列
• selectedEngine — エンジンID（推奨 — カタログについてはreferences/endpoints.mdを参照）またはフレンドリ名
• selectedQuery — 正確な検索語句または配列
• searchTermId — 単一の検索語句ID
• periodOffset — 整数、プリセットウィンドウをN期間戻します（0 = 現在、1 = 前、…）
• userTimezone — ユーザーのローカルの日付境界のためのIANA tz（例：Europe/Berlin）
• includeNotFoundExecutions — ブール値、「応答でブランドが見つかりませんでした」の実行をメトリクスに含めるかどうかを制御します（quirks.mdを参照）

data.ownBrandMetrics.historicalData.<aggregation>から応答を読み取ります（例：aggregation: "daily"を要求した場合は.daily）。各バケット配列 — visibilityScore、sentiment、mentions、sources、citations、citationCounts、avgPosition、detectionRate、top3、brandNotFound — はtimestampsと並行して実行されます。

3つの並列時系列がその隣にあります：

• data.ownBrandMetrics.topicMetricsData.<aggregation> — トピックごと
• data.ownBrandMetrics.engineMetricsData.<aggregation> — エンジンごと。上流ではドキュメント化されていません。通常、ウィンドウの集計値がフラットに見える場合に最も価値の高いカットです。エンジンレベルの変動は全体で相殺されるためです（quirks §25）
• data.competitorTimeSeriesData.<aggregation> — 競合他社ごと、自社ブランドは除外（quirks §16）

brandNotFound[]は非シグナルです — 検出率が100%未満のほぼすべてのブランドでtrueを読み取ります。代わりにdetectionRateを使用し、フラグから「ブランドが見つかりませんでした」を報告しないでください（quirks §2）。

これらの列を含むメトリクステーブルを表示します：日付、認知度、センチメント、言及数、引用数、平均順位、検出率%、トップ3%。その上に、スナップショットサマリー（ownBrandMetricsからの現在のスナップショット値 + trendsデルタ）を表示します。

ブランドランク（認知度による）— vs. 競合他社。 data.competitorMetrics[]から計算します（これには自社ブランドが含まれ、isOwnBrand: trueでフラグが立てられています）。ランク = 1 + (より大きいvisibilityScoreを持つエントリの数) — 同点の場合、ブランドは下がりません。これにより、ダッシュボードのランクが再現されます。応答にはエントリごとに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.comなど中立的なサードパーティサイトを含む）。そのため、競合他社が所有するサイトを特定するために使用しないでください。quirks.md §13bを参照してください。

リストを完全なものと呼ぶ前に、制限を確認してください。 デフォルトでは、応答は5,000個の個別URLと50ブランドに制限されています。data.paginationInfoが真実を報告します — citationsCapped、brandsCapped、responseTrimmed、capBypassed、maxCitations、maxBrands、totalCountとreturnedCount。uncapped: true（本文またはクエリパラメータ）を渡すとURLの制限が解除されます。50ブランドの制限や応答サイズガードは解除されません。deduplicated: trueは応答パスを重複排除し、data.searchTermsByIdを追加します。いずれかのキャップフラグがtrueの場合は、ユーザーに伝え、不完全なリストを全体像として提示するのではなく、ウィンドウを狭めるかフィルターを適用してください。quirks.md §13cを参照してください。

4. センチメント

/v1/metrics/sentimentは、追跡対象ブランドとすべての競合他社について、ウィンドウレベルのセンチメント集計とキーワードクラウドを返します（時系列ではありません。時系列センチメントには/reportのhistoricalData.<agg>.sentiment[]を使用してください）。同じ共有フィルターに加え、deduplicated: trueも使用できます。

2つの配列があり、スコープが異なります。data.brandSentiments[]は追跡対象ブランドのみ。data.companySentiments[]は自社ブランドを含む検出されたすべてのブランド（isOwnBrand: true）— 競合比較にはこちらを使用してください。brandSentimentsBySearchTerm[] / companySentimentsBySearchTerm[]は、同じ内訳を検索語句ごとに提供します。

エントリごと：avgSentiment（0～100のスケール、= totalSentimentScore / sentimentCount）、sentimentCount、executionCount、およびpositiveCount / neutralCount / negativeCount。センチメントはソースによって分割されています — webGrounding*（Webに基づくエンジン）とtrainingData*ブロックで、hasWebGrounding / hasTrainingDataブール値でゲート制御され、webGroundingSentimentByEngine[<engineId>] = {sum, count, avg}でエンジン別のスコアを取得できます。

2つの落とし穴 — これを報告する前にquirks.md §19を読んでください。 (1) positiveCount + neutralCount + negativeCountがsentimentCountになるとは限りません（これらは別々のパイプラインから来ています — センチメントが0で実行がカウントされる場合など）。(2) ウィンドウ外のデータがリークする可能性があります。詳細はquirks.mdを参照してください。

5. スナップショットとトレンド

ユーザーがメトリクス表を尋ねる場合、historicalDataの先頭に、ownBrandMetrics（センチメントを除く）からの現在のスナップショット値と、ownBrandMetrics.trendsからのデルタ（trendオブジェクト）を表示します。trendキーはすべて変更率です — 便利なフィルタリングのために、これらは別々のエンドポイントまたはサブパスではありません。スナップショットはlatestVisibility、latestSentiment、totalMentions、totalCitations、latestAvgPosition、latestDetectionRate、latestTop3を通じて利用可能で、trendsはvisibilityTrend、sentimentTrend、citationsTrend、avgPositionTrend、detectionRateTrend、top3Trendです。すべてのスナップショット値とトレンドは、レポート応答に常に含まれています — 個別のエンドポイントは必要ありません。

6. 経時的なブランドランク

data.competitorTimeSeriesDataには、各期間における各競合他社のvisibilityScoreが含まれています。期間ごとにランクを計算し、ランクの推移を提供できます。

パフォーマンスに関する注意： このデータは非常に大きくなる可能性があります。-oでファイルに保存し、node -eで処理してください。すべての競合他社を含む30日間の日次データは約60〜150 KBで、読み取り可能ですが、大きなウィンドウの場合は注意が必要です。

期間ごとにランクを計算する際、データが不完全な競合他社（期間に対してnull値を持つ）は、その期間のランキングから除外する必要があります。これにより、不正確な順位を防ぐことができます。

7. 検索語句レポート

/v1/metrics/search-terms-reportを使用します。includeAnswerTexts: trueは、応答に生のAIテキストを含めるため、ペイロードサイズが劇的に増加します。リクエスト本文は{brandId, searchTermIds: string[], includeAnswerTexts?: boolean, timeFrame?, isoStartDate?, isoEndDate?}です。searchTermIdsは必須です。応答は常に大きく、フィルタリングされていない場合、7つの語句で〜500 KBになる可能性があります。常に-oを使用してください。

なぜレポートではなく検索語句レポートを使用するのか：レポートはブランドの集計データを提供しますが、検索語句レポートは、各検索語句が個別にどのように機能しているかを示します。ダッシュボードの「検索語句」タブに相当します。

8. トピック分析

トピックはブランド内のサブカテゴリです。トピックはGET /v1/metrics/topics/{brandId}でリストされます。各トピックにはid、name、color、およびトピックの検索語句の数searchTermCountがあります。_orphanedは特殊なトピックで、どのトピックにも割り当てられていない検索語句をキャプチャします。ブランドに何が追跡されているかをよりよく理解するために、トピックをリストすることで、ユーザーが未整理の語句を発見するのに役立ちます。

成功するスキル呼び出しのパターン

1. 環境とAPIキーを確認します
2. 必要な場合はreferences/endpoints.mdを読み取ります
3. brands.jsonが存在する場合は読み取り、そうでない場合はブランドを取得します
4. ユーザーが要求したブランド名を解決します
5. レポート、引用、またはセンチメントデータを取得します
6. データをクリーンにフォーマットしてユーザーに提示します
7. 生のJSON応答を後で使用できるように保存します（該当する場合）

注意：仕事を分割してください。一度にすべてを実行しようとしないでください。まずブランドIDを取得し、次にメトリクスを取得します。Rankscale APIは複雑なため、一度に1つのエンドポイントを正しく実行する方が、複数のことを間違って実行するよりも優れています。