ChuniSupport API

ChuniSupportの楽曲・譜面データやプレイヤーデータを、Webアプリ、Discord Bot、分析ツールなどからJSONで利用できます。

楽曲・譜面データ通常楽曲の基本情報、譜面定数、ノーツ数、統計を取得します。

WORLD'S END WORLD'S END楽曲と譜面情報を取得します。

プレイヤーデータ・RATING 公開範囲に応じて、プレイヤー情報やRATINGを取得します。

スコア履歴楽曲ごとのスコア推移を取得し、グラフや振り返りに活用できます。

chunirec互換API chunirec向けの既存ツールで扱いやすい形式を提供します。

reiwa互換API reiwa互換形式のバージョン、楽曲・譜面データを取得します。

APIリファレンス

目的に応じて、次の項目から参照してください。

目的	エンドポイント
通常楽曲の一覧・詳細・統計	`GET /v1/songs`
WORLD’S END楽曲の一覧・詳細	`GET /v1/worldsend-songs`
プレイヤーのRATING	`GET /v1/users/:username/rating`
公式RATING・OVER POWER・OP%の履歴	`GET /v1/users/:username/rating-op-history`
プレイヤー情報・プレイ記録	`GET /v1/users/:username`
通常譜面・WORLD’S ENDのスコア履歴	`GET /v1/songs/:id/score-history/:difficulty` / `GET /v1/worldsend-songs/:id/score-history`
コースとコース記録	`GET /v1/courses` / `GET /v1/users/:username/records/courses`
既存ツールとの互換性	chunirec互換API / reiwa互換API

基本仕様

ベースURL: https://api.chunisupport.net
コンテンツタイプ: すべてのレスポンスは application/json です。
文字コード: UTF-8

認証

APIエンドポイントではAPIトークンが必要です。リクエストヘッダーに以下の形式でトークンを指定してください。

Authorization: Bearer <APIトークン>

APIトークンはChuniSupportの設定画面から発行できます。トークンの権限は、参照系APIのみを利用できる read と、参照系・更新系APIを利用できる read_write です。read_write トークンを発行できるのは、EDITOR または ADMIN のユーザーです。

公開ユーザーのデータを取得する場合も、有効なAPIトークンが必要です。非公開ユーザーのデータは、本人または承認済みフレンドのAPIトークンで参照できます。

楽曲情報の更新（PUT /v1/songs、PATCH /v1/songs/chart-constant）には、read_write トークンと、トークン所有者の EDITOR または ADMIN 権限の両方が必要です。read_write トークンだけではユーザーの権限は拡張されません。

レートリミット

すべてのエンドポイント共通で、権限ごとに以下の制限があります。

権限	15分あたりのリクエスト数
一般ユーザー	150
EDITOR / EXTDEV	3,000
ADMIN	150,000

制限を超えた場合は 429 Too Many Requests が返ります。

エラーレスポンス

エラー時は以下の形式で返ります。

{
  "error": {
    "status": 401,
    "code": "invalid_token",
    "message": "トークンが無効です。"
  }
}

フィールド	型	説明
`error.status`	number	HTTPステータスコード
`error.code`	string	エラーコード（スネークケース）
`error.message`	string	エラーの説明

主なエラーコード

エラーコード	HTTP	説明
`missing_token`	401	APIトークンが指定されていません
`invalid_token`	401	APIトークンが無効です
`forbidden`	403	権限が不足しています
`too_many_requests`	429	レートリミットを超過しました
`not_found`	404	指定されたリソースが見つかりません
`song_not_found`	404	指定された楽曲が見つかりません
`user_not_found`	404	指定されたユーザーが見つかりません
`chart_not_found`	404	指定された難易度の譜面が存在しません
`invalid_difficulty`	400	難易度の指定が無効です
`score_history_unsupported_difficulty`	400	スコア履歴非対応の難易度が指定されました
`validation_failed`	400 / 422	リクエストパラメータが不正です。未指定などは400、形式・値の検証エラーは422になります
`score_history_not_found`	404	スコア履歴が存在しません（未プレイ）
`player_metric_history_not_found`	404	プレイヤーの公式指標履歴が存在しません
`internal_error`	500	サーバー内部エラー