コンテンツにスキップ
ChuniSupport ガイド

楽曲・譜面

CHUNITHMのバージョン、通常楽曲（WORLD’S ENDを除く）の基本情報・譜面定数・統計・スコア履歴を取得するAPIと、楽曲情報を更新するAPIです。

GET /v1/master/versions

Section titled “GET /v1/master/versions”

サーバー起動日時点でリリース済みのバージョン一覧を、リリース日昇順で取得します。

リクエスト:

GET /v1/master/versions
Authorization: Bearer <APIトークン>

レスポンス: 200 OK

{
  "versions": [
    { "name": "CHUNITHM", "released_at": "2015-07-16" },
    { "name": "CHUNITHM PLUS", "released_at": "2016-02-04" },
    { "name": "CHUNITHM AIR", "released_at": "2016-08-25" }
  ]
}
フィールド型説明
versionsarray起動日時点でリリース済みのバージョン一覧（リリース日昇順）
versions[].namestringバージョン名
versions[].released_atstringリリース日（YYYY-MM-DD 形式）

GET /v1/songs

Section titled “GET /v1/songs”

WORLD’S ENDを除く全楽曲を取得します。削除済み楽曲は除外されます。

リクエスト:

GET /v1/songs
Authorization: Bearer <APIトークン>

レスポンス: 200 OK

{
  "songs": [
    {
      "id": "e9e66c56cb8388e9",
      "title": "GEMINI -C-",
      "reading": "GEMINIC",
      "artist": "Tatsh",
      "genre": "ORIGINAL",
      "bpm": 180,
      "release": "2016-03-17",
      "jacket": "45112e2818cf80a2",
      "official_idx": "202",
      "maxop": 86,
      "is_maxop_unknown": false,
      "op_target_difficulty": "MASTER",
      "is_new": false,
      "charts": {
        "BASIC": {
          "const": 4,
          "is_const_unknown": false,
          "notes": 549,
          "notes_designer": null
        },
        "ADVANCED": {
          "const": 7,
          "is_const_unknown": false,
          "notes": 769,
          "notes_designer": null
        },
        "EXPERT": {
          "const": 11.3,
          "is_const_unknown": false,
          "notes": 1319,
          "notes_designer": "鈴木さん"
        },
        "MASTER": {
          "const": 14.2,
          "is_const_unknown": false,
          "notes": 1587,
          "notes_designer": "rio -N-"
        },
        "ULTIMA": null
      }
    }
  ]
}
フィールド型説明
songsarray楽曲情報の配列
songs[].idstring楽曲のID（16進数16文字）
songs[].titlestring楽曲名
songs[].readingstring | null楽曲名の読み
songs[].artiststringアーティスト名
songs[].genrestring | nullジャンル名
songs[].bpmnumber | nullBPM
songs[].releasestring | nullリリース日（YYYY-MM-DD 形式）
songs[].jacketstring | nullジャケット画像ファイル名
songs[].official_idxstring公式ID
songs[].maxopnumber全譜面のうち最も定数が高い譜面で理論値を取ったときのOVER POWER値
songs[].is_maxop_unknownbooleanmaxop が暫定値である可能性がある場合に true
songs[].op_target_difficultystring | nullmaxop の算出対象となった譜面の難易度
songs[].is_newboolean新曲枠の対象楽曲の場合に true
songs[].chartsobject譜面情報のマップ。キーは BASIC、ADVANCED、EXPERT、MASTER、ULTIMA の順
songs[].charts[key].constnumber譜面定数
songs[].charts[key].is_const_unknownboolean譜面定数が未確定の場合 true
songs[].charts[key].notesnumber | nullノーツ数
songs[].charts[key].notes_designerstring | nullノーツデザイナー

譜面が存在しない難易度は null になります。

PUT /v1/songs

Section titled “PUT /v1/songs”

通常楽曲（WORLD’S ENDを除く）の楽曲情報と譜面情報を一括更新します。既存データの修正専用で、新規追加・削除は行いません。

権限: read_write トークン、および EDITOR または ADMIN

リクエスト:

PUT /v1/songs
Authorization: Bearer <APIトークン>
Content-Type: application/json
[
  {
    "id": "e9e66c56cb8388e9",
    "title": "GEMINI -C-",
    "reading": "GEMINIC",
    "artist": "Tatsh",
    "genre": "ORIGINAL",
    "bpm": 180,
    "released_at": "2016-03-17",
    "jacket": "45112e2818cf80a2",
    "charts": {
      "MASTER": {
        "const": 14.2,
        "is_const_unknown": false,
        "notes": 1587,
        "notes_designer": "rio -N-"
      }
    }
  }
]
フィールド型必須説明
[].idstring✓楽曲のID（16文字の小文字16進数）
[].titlestring✓楽曲名
[].readingstring | null楽曲名の読み
[].artiststring✓アーティスト名
[].genrestring | nullジャンル名
[].bpmnumber | nullBPM
[].released_atstring | nullリリース日（YYYY-MM-DD 形式）
[].jacketstring | nullジャケット画像ファイル名
[].chartsobject譜面情報のマップ。キーは BASIC、ADVANCED、EXPERT、MASTER、ULTIMA
[].charts[key].constnumber✓譜面定数
[].charts[key].is_const_unknownboolean✓譜面定数が未確定の場合 true
[].charts[key].notesnumber | nullノーツ数
[].charts[key].notes_designerstring | nullノーツデザイナー

レスポンス: 204 No Content

エラー:

コードHTTP説明
validation_failed422リクエストパラメータが不正です
forbidden403read_write トークン、または EDITOR / ADMIN 権限が必要です

PATCH /v1/songs/chart-constant

Section titled “PATCH /v1/songs/chart-constant”

通常楽曲の既存譜面について、公式ID・難易度名の先頭3文字・譜面定数だけを指定して更新します。更新後は is_const_unknown が false になります。

権限: read_write トークン、および EDITOR または ADMIN

リクエスト:

PATCH /v1/songs/chart-constant
Authorization: Bearer <APIトークン>
Content-Type: application/json
{
  "official_idx": "202",
  "difficulty": "MAS",
  "const": 14.7
}
フィールド型必須説明
official_idxstring✓公式ID（最大10文字）
difficultystring✓難易度名の先頭3文字。BAS / ADV / EXP / MAS / ULT（大文字・小文字を区別しない）
constnumber✓譜面定数（0.0～16.0、小数第1位まで）

レスポンス: 200 OK

更新後の楽曲オブジェクトを返します。フィールドの詳細は GET /v1/songs/:id を参照してください。

エラー:

コードHTTP説明
validation_failed400リクエストパラメータが不正です
invalid_difficulty400難易度または譜面定数が不正です
forbidden403read_write トークン、または EDITOR / ADMIN 権限が必要です
song_not_found404公式IDに対応する通常楽曲が見つかりません
chart_not_found404対象難易度の譜面が存在しません

GET /v1/songs/:id

Section titled “GET /v1/songs/:id”

指定された楽曲の詳細を取得します。

リクエスト:

GET /v1/songs/e9e66c56cb8388e9
Authorization: Bearer <APIトークン>

パスパラメータ:

パラメータ型説明
idstring楽曲のID（16文字）

レスポンス: 200 OK

{
  "id": "e9e66c56cb8388e9",
  "title": "GEMINI -C-",
  "reading": "GEMINIC",
  "artist": "Tatsh",
  "genre": "ORIGINAL",
  "bpm": 180,
  "release": "2016-03-17",
  "jacket": "45112e2818cf80a2",
  "official_idx": "202",
  "maxop": 86,
  "is_maxop_unknown": false,
  "op_target_difficulty": "MASTER",
  "is_new": false,
  "charts": {
    "BASIC": {
      "const": 4,
      "is_const_unknown": false,
      "notes": 549,
      "notes_designer": null
    },
    "ADVANCED": {
      "const": 7,
      "is_const_unknown": false,
      "notes": 769,
      "notes_designer": null
    },
    "EXPERT": {
      "const": 11.3,
      "is_const_unknown": false,
      "notes": 1319,
      "notes_designer": "鈴木さん"
    },
    "MASTER": {
      "const": 14.2,
      "is_const_unknown": false,
      "notes": 1587,
      "notes_designer": "rio -N-"
    },
    "ULTIMA": null
  }
}

フィールドの詳細は GET /v1/songs を参照してください。

エラー:

コードHTTP説明
song_not_found404指定された楽曲が見つかりません

GET /v1/songs/:id/stats/:difficulty

Section titled “GET /v1/songs/:id/stats/:difficulty”

指定楽曲の特定難易度におけるレーティング帯別の統計情報を取得します。

リクエスト:

GET /v1/songs/e9e66c56cb8388e9/stats/master
Authorization: Bearer <APIトークン>

パスパラメータ:

パラメータ型説明
idstring楽曲のID（16文字）
difficultystring難易度名（小文字）: basic、advanced、expert、master、ultima、worldsend

レスポンス: 200 OK

{
  "song_id": "e9e66c56cb8388e9",
  "stats": [
    {
      "rating_band": "ALL",
      "rank": {
        "aaal": 0,
        "s": 0,
        "sp": 0,
        "ss": 0,
        "ssp": 0,
        "sss": 3,
        "sssp": 0,
        "max": 0
      },
      "combo": {
        "none": 3,
        "fc": 0,
        "aj": 0,
        "ajc": 0
      },
      "clear": {
        "failed": 0,
        "clear": 0,
        "hard": 0,
        "brave": 3,
        "absolute": 0,
        "catastrophy": 0
      },
      "average_score": 1008991,
      "median_score": 1009123,
      "player_count": 3
    },
    {
      "rating_band": "17.5",
      "rank": {
        "aaal": 0,
        "s": 0,
        "sp": 0,
        "ss": 0,
        "ssp": 0,
        "sss": 3,
        "sssp": 0,
        "max": 0
      },
      "combo": {
        "none": 3,
        "fc": 0,
        "aj": 0,
        "ajc": 0
      },
      "clear": {
        "failed": 0,
        "clear": 0,
        "hard": 0,
        "brave": 3,
        "absolute": 0,
        "catastrophy": 0
      },
      "average_score": 1008991,
      "median_score": 1009123,
      "player_count": 3
    }
  ]
}
フィールド型説明
song_idstring楽曲の識別ID
statsarrayレーティング帯別の統計配列。先頭要素は必ず rating_band: "ALL"（全体統計）
stats[].rating_bandstringレーティング帯ラベル。"ALL" または個別帯（例: "15.0"、"17.6+"）
stats[].rankobjectランク別人数（aaal、s、sp、ss、ssp、sss、sssp、max）
stats[].comboobjectコンボランプ別人数（none、fc、aj、ajc）
stats[].clearobjectクリアランプ別人数（failed、clear、hard、brave、absolute、catastrophy）
stats[].average_scorenumber | nullレーティング帯別平均スコア（レコード0件の場合は null）
stats[].median_scorenumber | nullレーティング帯別中央スコア（レコード0件の場合は null）
stats[].player_countnumberレーティング帯別プレイヤー数

エラー:

コードHTTP説明
invalid_difficulty400無効な難易度が指定されました
song_not_found404指定された楽曲が見つかりません
chart_not_found404指定された難易度の譜面が存在しません

GET /v1/songs/:id/score-history/:difficulty

Section titled “GET /v1/songs/:id/score-history/:difficulty”

指定楽曲の指定難易度におけるスコア履歴を取得します。各譜面の現行ベストと過去のベストを新しい順で返します。履歴は譜面ごとに最大50件で、レスポンス先頭の現行ベストを含めると最大51件です。

認証: APIトークン必須。非公開ユーザーは本人または承認済みフレンドのみ参照できます。

リクエスト:

GET /v1/songs/5a9ab66f9aea05d3/score-history/master?username=kjumanenobikto
Authorization: Bearer <APIトークン>

パスパラメータ:

パラメータ型説明
idstring楽曲のID（16文字）
difficultystring難易度名（小文字）: expert、master、ultima

クエリパラメータ:

パラメータ型必須説明
usernamestring✓対象ユーザー名

レスポンス: 200 OK

{
  "entries": [
    {
      "score": 1009566,
      "clear_lamp": "ABSOLUTE",
      "combo_lamp": "ALL JUSTICE",
      "full_chain": null,
      "updated_at": "2026-06-21T23:58:02+09:00"
    },
    {
      "score": 1008280,
      "clear_lamp": "HARD",
      "combo_lamp": null,
      "full_chain": null,
      "updated_at": "2026-06-10T21:58:32+09:00"
    }
  ]
}
フィールド型説明
entriesarrayスコア履歴エントリの配列（新しい順）
entries[].scorenumberスコア
entries[].clear_lampstring | nullクリアランプ名称
entries[].combo_lampstring | nullコンボランプ名称
entries[].full_chainstring | nullフルチェイン名称
entries[].updated_atstring更新日時（ISO8601）

エラー:

コードHTTP説明
validation_failed400username が未指定です
score_history_unsupported_difficulty400expert、master、ultima 以外の難易度が指定されました
score_history_not_found404スコア履歴が存在しません（未プレイ）
user_not_found404ユーザーが見つからない、または非公開設定のため閲覧できません