nba-data

NBA データ

クエリを作成する前に、エンドポイント、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 nba get_scoreboard
sports-skills nba get_standings --season=2025
sports-skills nba get_teams

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

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

• シーズンの年は、システムプロンプトの currentDate から導き出してください。ハードコードしないでください。
• チーム名のみが指定されている場合は、チーム固有のコマンドを使用する前に get_teams を呼び出してチーム ID を特定してください。

シーズンの選び方

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

• ユーザーがシーズンを指定した場合は、そのまま使用してください。
• ユーザーが「現在」「今シーズン」と指定した場合、または指定がない場合：NBA シーズンは 10 月から 6 月までです。現在の月が 10 月から 12 月の場合、進行中のシーズンの年は現在の年と一致します。1 月から 6 月の場合、進行中のシーズンは前年の暦年に始まっているため、その年をシーズンとして使用してください。

コマンド

コマンド	説明
get_scoreboard	NBA のライブスコア／最近のスコア
get_standings	カンファレンス別順位
get_teams	NBA 全 30 チーム
get_team_roster	チームの全ロスター
get_team_schedule	特定チームのスケジュール
get_game_summary	詳細なボックススコアと得点プレー
get_leaders	NBA の統計リーダー
get_news	NBA のニュース記事
get_play_by_play	試合の全プレー記録
get_win_probability	勝率チャートデータ
get_schedule	特定日付の試合（シーズンでの絞り込みなし。get_team_schedule を参照）
get_injuries	全チームの負傷者情報
get_transactions	最近の移籍情報
get_futures	先物／オッズ市場
get_depth_chart	チームのデプスチャート
get_team_stats	チームの統計プロフィール
get_player_stats	選手の統計プロフィール
find_nba_player	NBA Stats の選手レジストリを検索（全時代）
get_nbastats_game_log	NBA Stats によるリーグの試合記録 — 1946 年までさかのぼる履歴があり、NBA の試合 ID を含みます。選手の試合記録には player_or_team="player" または player=<name or id> を指定します
get_nbastats_player_career	NBA Stats によるシーズンごとのキャリア統計
get_nbastats_team_stats	NBA Stats によるリーグチーム統計 — 高度なレーティング、ペース、フォー・ファクター
get_nbastats_shot_chart	NBA Stats によるシュートごとのコート座標
get_nbastats_play_by_play	NBA Stats による過去シーズンの座標付きプレー記録
get_nbastats_advanced_boxscore	高度なボックススコア（レーティング、使用率）を NBA Stats 経由で取得
get_live_scoreboard	リアルタイムスコア。優先ソースは cdn.nba.com、フォールバックは ESPN
get_live_boxscore	リアルタイムのボックススコア。優先ソースは cdn.nba.com、フォールバックは ESPN
get_live_playbyplay	リアルタイムのプレー記録。最新のプレーが先頭
get_player_live_stats	今日の試合における 1 人の選手のリアルタイム統計

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

NBA の長い統計結果を整形する

get_nbastats_game_log、get_nbastats_team_stats、get_nbastats_shot_chart は sort_by、descending、limit、fields を受け付けます。シーズン全体ではなく、 必要な行と列を指定できます。

# Miami's five highest-scoring games, four columns each
sports-skills nba get_nbastats_game_log --season=2025 --team=MIA \
  --sort_by=pts --limit=5 --fields=wl,pts

• sort_by：並べ替えに使う列を1つ指定します。数値（および数値文字列）は数値として並べ替えられ、欠損値は常に最後になります。
• descending：true（デフォルト）または false を指定します。sort_by と併用した場合のみ有効です。
• limit：正の整数を指定します。並べ替えの後に適用されます。
• fields：保持する列をカンマ区切りで指定します。以下の識別列と sort_by 列は常に保持されます。
• 不明な sort_by／fields 列を指定すると、有効な列を示すエラーが返されます。
• これらのいずれかを設定すると、レスポンスに total_rows（limit 適用前の該当行数）と returned_rows が追加されます。いずれも設定しない場合、出力は変わりません。これらはデータ取得後に適用されるため、上流へのリクエストやその再生エントリーには影響しません。

コマンド	fields で常に保持される列
get_nbastats_game_log	game_id、game_date、team_abbreviation、matchup
get_nbastats_game_log（選手の行）	game_id、game_date、player_id、team_abbreviation、matchup
get_nbastats_team_stats	team_id、team_name、team_abbreviation
get_nbastats_shot_chart	game_id、game_date、period

列名は NBA.com の表記を小文字にしたものです（pts、fg3m、plus_minus、shot_distance）。

ESPN と NBA Stats を併用する

get_nbastats_* コマンドは stats.nba.com を読み込みます。ここでは、ESPN のエンドポイントにはない分析データ（高度な評価指標、シュート座標、詳細な過去データ）を取得できます。 2つのデータソースでは、互いに異なる ID システムが使われています。

• 試合 ID。 NBA Stats では10桁の ID（"0022400061"）、ESPN ではイベント ID（"401704627"）が使われます。共通の列はありません。試合日と両チームの略称を使って結合してください。
• チーム略称。 6チームの表記が異なります。ESPN の GS／NO／NY／SA／UTAH／WSH に対し、NBA では GSW／NOP／NYK／SAS／UTA／WAS が使われます。get_nbastats_* のチームフィルターはどちらの表記も受け付け、結果の行には両方の略称（team_abbreviation と team_abbreviation_espn）が含まれます。
• 選手 ID。 NBA の人物 ID（"203999"）と ESPN のアスリート ID は別のものです。find_nba_player で名前を解決してください。アクセント記号を含まない表記でも、アクセント記号付きの名前に一致します（"jokic" で "Nikola Jokić" が見つかります）。
• シーズン。 開始年を指定してください（season=2024 は2024-25を意味します）。NBA 形式（"2024-25"）も使用できます。
• 日付。 game_date は、試合ログとシュートチャートのどちらでも YYYY-MM-DD 形式です。

stats.nba.com は、クライアントやリクエスト量に応じてスロットリングを行います。大量のリクエストを短時間に送信した場合（および多くのデータセンター／クラウド IP からのアクセス）、拒否されるのではなく、応答がひそかに遅延させられます。その場合、コマンドは説明付きのエラーを返してすぐに失敗します。再試行する前に待機してください。過度なリクエストの送信は避けてください。レスポンスはキャッシュされ、ESPN を利用するコマンドと get_live_* コマンドには影響しません。

例

例1：今日のスコア ユーザー：「今日のNBAのスコアは？」 操作：

1. get_scoreboard() を呼び出す 結果：スコアと試合状況を含む、開催中および直近のNBA全試合

例2：カンファレンスの順位表 ユーザー：「ウェスタン・カンファレンスの順位表を見せて」 操作：

1. currentDate からシーズン年を導き出す
2. get_standings(season=<derived_year>) を呼び出す
3. 結果をウェスタン・カンファレンスで絞り込む 結果：チームごとの勝敗、勝率、首位との差を含むウェスタン・カンファレンスの順位表

例3：チームのロースター ユーザー：「レイカーズのロースターには誰がいる？」 操作：

1. get_team_roster(team_id="13") を呼び出す 結果：選手名、ポジション、背番号、身長、体重を含むレイカーズのロースター全員

例4：試合のボックススコア ユーザー：「昨夜のセルティックスの試合の詳細なボックススコアを見せて」 操作：

1. get_scoreboard(date="<yesterday>") を呼び出し、event_idを確認する
2. get_game_summary(event_id=<id>) を呼び出し、詳細なボックススコアを取得する 結果：選手ごとのスタッツと得点プレーを含む完全なボックススコア

例5：負傷者情報 ユーザー：「レイカーズで負傷しているのは誰？」 操作：

1. get_injuries() を呼び出す
2. 結果をロサンゼルス・レイカーズ（team_id=13）で絞り込む 結果：選手名、ポジション、状況、負傷の種類を含むレイカーズの負傷者一覧

例6：選手のスタッツ ユーザー：「今シーズンのレブロンのスタッツを見せて」 操作：

1. currentDate からシーズン年を導き出す
2. get_player_stats(player_id="1966", season_year=<derived_year>) を呼び出す 結果：カテゴリごとの値、順位、1試合平均を含むシーズンスタッツ

存在しないコマンド — 決して呼び出さないでください

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

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

エラー処理

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

1. エラーを表に出さずに捕捉し、別の方法を試します
2. IDではなくチーム名が指定された場合は、まず get_teams を使用してIDを確認します
3. 代替手段をすべて試した後に限り、簡潔なメッセージで失敗を伝えます

トラブルシューティング

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

エラー：IDでチームが見つかりません 原因：誤った、または古いESPNチームIDが使用されています 解決策：get_teams を呼び出し、現在の全30NBAチームとそのIDの一覧を取得します

エラー：未来の試合のデータが返されません 原因：ESPNがデータを返すのは、終了済みまたは進行中の試合のみです 解決策：今後の試合の詳細を確認するには get_schedule を使用します。get_scoreboard の対象は開催中または直近の試合のみです

エラー：オフシーズン中で、スコアボードのイベント数が0件です 原因：オフシーズン（7月〜9月）には試合が予定されていません 解決策：代わりに get_standings または get_news を使用します。シーズンの再開時期を確認するには get_schedule を使用します