cbb-data

カレッジバスケットボールデータ（CBB）

クエリを作成する前に、エンドポイント、カンファレンス ID、チーム ID、データの構造について references/api-reference.md を確認してください。

セットアップ

初めて使用する前に、CLI を利用できるか確認してください：

which sports-skills || pip install sports-skills

pip install が Python のバージョンエラーで失敗する場合、このパッケージには Python 3.10 以降が必要です。互換性のある Python を探してください：

python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

API キーは必要ありません。

クイックスタート

Python のインポートパスに関する問題を避けられるため、CLI の使用を推奨します：

sports-skills cbb get_scoreboard
sports-skills cbb get_rankings
sports-skills cbb get_standings --group=23

重要：クエリを実行する前に

重要：データエンドポイントを呼び出す前に、以下を確認してください：

• シーズンの年は、システムプロンプトの currentDate から導き出してください。ハードコードしないでください。
• 順位表では、group パラメーターに正しいカンファレンス ID を設定してください（references/api-reference.md を参照）。
• チーム名しか指定されていない場合は、get_teams を使ってチーム ID を解決してください。

シーズンの選び方

システムプロンプトの日付から現在の年を導き出してください（例：currentDate: 2026-02-28 → 現在の年は 2026 年）。

• ユーザーがシーズンを指定した場合は、そのまま使用してください。
• ユーザーが「現在」「今シーズン」と指定した場合、または指定がない場合：CBB のシーズンは 11 月から 4 月です。現在の月が 11 月または 12 月なら、season = current_year + 1 を使用してください。1 月から 4 月なら、season = current_year を使用してください。5 月から 10 月（オフシーズン）なら、season = current_year を使用してください（直近で終了したシーズン）。

重要：大学とプロの違い

• 順位表はカンファレンスごとです — group パラメーターで絞り込んでください
• リーダーランキングの代わりにランキングを使用します — 大学では AP トップ 25 とコーチ投票を使用します
• ランキング入りしたチームは、スコアボードの競技者データに rank フィールドがあります（ランク外の場合は null）
• D1 のチームは 360 以上 — シーズン中は 1 日に多数の試合があります（カンファレンス戦期間中は 50 試合以上）
• マーチ・マッドネス — NCAA トーナメントは 3 月から 4 月にかけて開催され、68 チームが出場します

コマンド

コマンド	説明
get_scoreboard	大学バスケットボールのライブスコア／直近のスコア
get_standings	カンファレンス別順位表（group パラメーターを使用）
get_teams	D1 男子バスケットボールの全チーム（360 以上）
get_team_roster	チームの全ロスター
get_team_schedule	特定チームのスケジュール
get_game_summary	詳細なボックススコアと選手スタッツ
get_rankings	AP トップ 25 とコーチ投票のランキング
get_news	大学バスケットボールのニュース
get_play_by_play	試合の全プレー記録
get_win_probability	勝率チャートデータ
get_schedule	日付またはシーズンのスケジュール
get_futures	フューチャーズ／オッズ市場（全米選手権など）
get_team_stats	チームの統計プロフィール
get_player_stats	選手の統計プロフィール
get_ncaa_scoreboard	NCAA 公式スコアボード — D1、D2、D3
get_ncaa_schedule	試合がある日付（公式インデックス）
get_ncaa_game	NCAA 公式試合情報
get_ncaa_boxscore	NCAA 公式ボックススコア
get_ncaa_play_by_play	公式プレー記録
get_ncaa_bracket	ライブスコア付きマーチ・マッドネスのトーナメント表
get_ncaa_schools	NCAA の学校インデックス（全ディビジョン）
get_power_index	D1 チームの BPI（バスケットボール・パワー・インデックス）評価
get_tournament_projections	シード、地区、勝ち進む確率を含む NCAA トーナメント予測
compare_teams	BPI 評価とシーズン成績で 2 チームを比較
find_upset_candidates	BPI とシード順位の差に基づく番狂わせ候補

パラメーター一覧と戻り値の構造については、references/api-reference.md を参照してください。

公式 NCAA バックエンド

get_ncaa_* コマンドは、NCAA 独自のエンドポイント（sdataprod.ncaa.com + ncaa.com）を読み取ります。ESPN ではカバーされない情報を取得できます。

• division="d2"／"d3" を指定した D2 と D3 のスコアボード。ESPN の大学バスケットボール情報は D1 中心です。
• どちらのスコアボードも、現在はデフォルトで Division I の全試合を返します。ESPN を利用する get_scoreboard／get_schedule は、以前、ESPN のグループ指定なしのデフォルト（トップ 25 のみ）を引き継いでいたため、通常の金曜日には約 24 試合ではなく 1 試合しか表示されませんでした。ESPN の絞り込まれたグループを指定するには、group を明示的に渡してください。
• ライブスコア付きの 公式 March Madness トーナメント表：get_ncaa_bracket。
• 公式の試合詳細：get_ncaa_game、get_ncaa_boxscore、get_ncaa_play_by_play。
• 大学一覧（全ディビジョン、約 1,200 校）：get_ncaa_schools。

NCAA の試合 ID（get_ncaa_scoreboard から取得）と ESPN のイベント ID に共通するものはありません。試合日とチーム名で照合してください。NCAA は試合 ID を再発行するため、保存した ID ではなく、最新の get_ncaa_scoreboard の呼び出しから取得してください。試合にチームが割り当てられていない場合、get_ncaa_bracket は仮のトーナメント表ではなくエラーを返します。2020 年のトーナメントは中止されており、今後のトーナメント表は出場チームが発表されると表示されます。get_ncaa_schools を除くすべての get_ncaa_* コマンドは、NCAA の GraphQL 永続クエリを使用します。そのハッシュは ncaa.com の再デプロイ時に変更されます。変更があった場合は明示的に通知され、同じ D1 の試合を ESPN ベースの get_scoreboard／get_schedule で確認できます。

例

例 1：現在のランキング ユーザー：「大学バスケットボールのランキングは？」 アクション：

1. get_rankings() を呼び出します 結果：順位、前回の順位、成績、ポイントを含む AP トップ 25 とコーチズ・ポール

例 2：カンファレンスの順位表 ユーザー：「SEC のバスケットボール順位表を見せて」 アクション：

1. currentDate からシーズンの年を求めます
2. get_standings(group=23, season=<derived_year>) を呼び出します（group 23 = SEC） 結果：各チームの勝敗記録を含む SEC の順位表

例 3：今日のスコア ユーザー：「今日の大学バスケットボールのスコアは？」 アクション：

1. get_scoreboard() を呼び出します 結果：スコアとランキング状況を含む、試合中および直近の CBB 全試合

例 4：チームのロースター ユーザー：「Duke のロースターを見せて」 アクション：

1. get_team_roster(team_id="150") を呼び出します 結果：名前、ポジション、背番号を含む Duke の全ロースター

例 5：March Madness の優勝予想 ユーザー：「March Madness の優勝候補は？」 アクション：

1. get_futures(limit=10) を呼び出します 結果：オッズ値を含む、全米選手権の有力候補

例 6：チームの統計 ユーザー：「Duke のチーム統計を見せて」 アクション：

1. currentDate からシーズンの年を求めます
2. get_team_stats(team_id="150", season_year=<derived_year>) を呼び出します 結果：値、順位、1 試合あたりの平均値を含む、カテゴリ別の Duke のシーズン統計

存在しないコマンド — 絶対に呼び出さないでください

• get_odds／get_betting_odds — 利用できません。予測市場のオッズには、polymarket または kalshi のスキルを使用してください。
• search_teams — 存在しません。代わりに get_teams を使用してください。
• get_box_score — 存在しません。代わりに get_game_summary を使用してください。
• get_player_ratings — 存在しません。代わりに get_player_stats を使用してください。
• get_ap_poll — 存在しません。代わりに get_rankings を使用してください。

上記のコマンド表に記載されていないコマンドは存在しません。

エラー処理

コマンドが失敗した場合、生のエラーをユーザーに見せないでください。代わりに、次の手順に従ってください。

1. イベントが見つからない場合は、オフシーズンかどうかを確認します（CBB の開催期間は 11 月から 4 月です）。
2. グループフィルターを指定していないのに順位表が空の場合は、特定のカンファレンスを指定してみます。
3. March Madness の期間中は、スコアボードにトーナメントの試合が表示されます。
4. 代替手段をすべて試した後に限り、わかりやすいメッセージで失敗を報告します。

トラブルシューティング

エラー：sports-skills コマンドが見つかりません 原因：パッケージがインストールされていません 解決策：pip install sports-skills を実行してください

エラー：スコアボードに試合が見つかりません 原因：CBB のシーズンは 11 月から 4 月までです。シーズンオフのスコアボードは空になります 解決策：年間を通じて get_rankings または get_news を使用してください。シーズン再開時期は get_schedule で確認してください

エラー：返される試合が多すぎて、絞り込むのが困難です 原因：シーズン中は、1 日に 50 試合以上が予定されています 解決策：--group でカンファレンスを絞り込むか、--limit で結果数を制限してください

エラー：ランキングが空です 原因：ランキングはシーズン中（11 月から 3 月まで）のみ、毎週発表されます 解決策：シーズンオフには get_news を使用してください。ランキングは 11 月に再開します