nhl-data

NHL Data

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

重要：クエリを実行する前に必ず確認

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

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

シーズンの選び方

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

• ユーザーがシーズンを指定した場合は、そのまま使用します。
• ユーザーが「現在の」「今シーズン」と指定した場合、またはシーズンを指定していない場合：NHL のシーズンは 10 月から 6 月までです。現在の月が 10 月から 12 月の場合、開催中のシーズンの年は現在の年と一致します。1 月から 6 月の場合、開催中のシーズンは前の暦年に始まっているため、その年をシーズンとして使用します。
• **例：**現在の日付が 2026 年 2 月の場合、開催中のシーズンは 2025 年 10 月に始まっているため、シーズンには 2025 を使用します。

コマンド

コマンド	説明
get_scoreboard	NHL のリアルタイム／最近のスコア
get_standings	カンファレンス別・ディビジョン別の順位表
get_teams	NHL の全チーム
get_team_roster	チームの全ロースター
get_team_schedule	特定チームの試合日程
get_game_summary	詳細なボックススコアと得点プレー
get_leaders	NHL の統計リーダー
get_news	NHL のニュース記事
get_play_by_play	試合の全プレーバイプレー
get_schedule	特定の日付の試合（シーズンによる絞り込みなし。get_team_schedule を参照）
get_injuries	全チームの負傷者情報
get_transactions	最近の選手移籍
get_futures	先物／オッズ市場
get_team_stats	チームの統計プロフィール
get_player_stats	選手の統計プロフィール
find_nhl_player	NHL の選手登録簿を名前で検索
get_nhlstats_schedule	NHL API 経由の試合日程 — チームのシーズンはオリジナル・シックス時代まで、NHL の試合 ID
get_nhlstats_player_stats	NHL API 経由の複数リーグにわたるシーズン別の通算成績
get_nhlstats_player_game_log	NHL API 経由の特定選手のシーズン内の試合記録（対戦相手、ホーム／アウェイ、結果、スタッツ）
get_nhlstats_play_by_play	氷上の x/y 座標、ゾーン、シュートの種類を含むプレーバイプレー
get_nhlstats_boxscore	NHL API 経由の完全なボックススコア（スケーター＋ゴールキーパー）
get_nhlstats_standings	現在または任意の過去の日付の順位表（1917 年まで遡ります）
get_nhlstats_leaders	カテゴリー別のスケーターとゴールキーパーのリーダー

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

ESPN と NHL API の併用

get_nhlstats_* コマンドは api-web.nhle.com（NHL の現行 API）を読み取ります。 （コミュニティのドキュメントで今もよく説明されている、廃止済みの statsapi.web.nhl.com は、もう名前解決できません。）この API には、ESPN にない分析データが含まれています。氷上でのショット座標、リーグ横断のキャリア記録、ゴーリーのリーダー情報、Original Six 時代までさかのぼる履歴などです。2 つのデータソースでは、互いに無関係な ID システムが使われています。

• 試合 ID。 NHL の ID は、シーズン／試合種別／試合番号を表す 10 桁の数字です （2023030417）。ESPN では 9 桁のイベント ID が使われます（401559593）。共通の列はないため、試合日とチームで結合してください。
• チーム略称。 5 チームで表記が異なります。ESPN の LA／NJ／SJ／TB／UTAH に対し、NHL では LAK／NJD／SJS／TBL／UTA が使われます。すべての get_nhlstats_* チームフィルターでは、どちらの表記も使えます。また、行には両方の表記が含まれます（team_abbreviation、team_abbreviation_espn）。
• 選手 ID。 NHL の選手 ID（8478402）と ESPN のアスリート ID は無関係です。find_nhl_player で名前を検索してください。アクセント記号を除いた綴りでも、アクセント付きの名前に一致します（「stutzle」で「Tim Stützle」が見つかります）。
• キャリア記録は複数のリーグにまたがります。 get_nhlstats_player_stats は、選手が出場したすべてのリーグの記録を返します。各行には league と is_nhl のラベルが付いています。キャリア成績を合計する前に、is_nhl で絞り込んでください。シーズン途中に移籍した選手には、チームごとに NHL の行が 1 つずつあり、さらに team: "TOTAL" の行もあります（カウントスタッツは合計され、率のスタッツは省略されます。is_total: true）。合計時には is_total の行を除外してください。
• シーズン。 開始年を渡してください（season=2024 は 2024-25 シーズンを意味します）。NHL 形式（"20242025"）も使用できます。
• 試合の決着方法。 status は NHL の試合状態です（最終結果はすべて OFF／FINAL）。日程行とボックススコアの decided_by は REG、OT、SO のいずれかです（試合終了までは null）。シュートアウトのスコアは公式結果に従います。シュートアウトで 1-1 の試合に勝った場合、勝者に 1 ゴールが加算され、2-1 となります。
• ブロックショット。 get_nhlstats_play_by_play の blocked-shot 行にある team_id と player は、ショットを打った側（NHL のイベント所有者）を示します。ボックススコアの blockedShots は守備側に記録され、blocking_player と blocking_team_id に示されます。ブロック数を数えるときは blocking_team_id を使ってください。

例

例 1：今日のスコア ユーザー：「今日の NHL のスコアは？」 アクション：

1. get_scoreboard() を呼び出す 結果：ライブ中および直近の NHL の全試合とスコア、試合状態

例 2：カンファレンス順位 ユーザー：「イースタン・カンファレンスの順位を見せて」 アクション：

1. currentDate からシーズン年を導き出す
2. get_standings(season=<derived_year>) を呼び出す
3. 結果をイースタン・カンファレンスで絞り込む 結果：勝利数・敗戦数・延長戦敗戦数、ポイント、レギュレーション勝利数を含むイースタン・カンファレンスの順位

例 3：チームのロースター ユーザー：「メープルリーフスのロースターには誰がいる？」 アクション：

1. get_team_roster(team_id="21") を呼び出す 結果：選手名、ポジション、背番号、シュート／キャッチの利き手を含むメープルリーフスの完全なロースター

例 4：試合のボックススコア ユーザー：「昨夜のブルーインズの試合の詳細なボックススコアを見せて」 アクション：

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

例 5：スタンレー・カップの優勝オッズ ユーザー：「スタンレー・カップの優勝オッズは？」 アクション：

1. get_futures(limit=10) を呼び出す 結果：スタンレー・カップの優勝候補上位とオッズ

例 6：選手のスタッツ ユーザー：「コナー・マクデイビッドのスタッツを見せて」 アクション：

1. currentDate からシーズン年を導き出す
2. get_player_stats(player_id="3895074", 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 を呼び出して、ID 付きの現在の全 NHL チーム一覧を取得します（Seattle Kraken や Utah Mammoth などの拡張チームの ID は連番ではありません）

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

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