nfl-data

NFL データ

クエリを作成する前に、エンドポイント、ID の規則、データの形式について references/api-reference.md を確認してください。

セットアップ

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

which sports-skills || pip install sports-skills

pip install が失敗した場合（パッケージが見つからない、または Python のバージョンエラー）、GitHub からインストールしてください：

pip install git+https://github.com/machina-sports/sports-skills.git

このパッケージには 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 キーは不要です。

nflverse を利用するコマンド（get_nflverse_*）を使う場合は、NFL 用の追加パッケージをインストールしてください：

pip install sports-skills[nfl]

Python 3.10 以降では、nflreadpy（推奨バックエンド）と、スケジュール以外のほとんどの nflverse データに必要な pyarrow がインストールされます。nflreadpy は Python 3.10 以降が必要なため、Python 3.9 では代わりに nfl-data-py がインストールされます。

nfl-data-py バックエンドは機能が限定された代替手段です。get_nflverse_team_stats は利用できず、説明付きのエラーが返されます。nflverse のすべてのデータを利用するには、Python 3.10 以降を使用してください。

クイックスタート

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

sports-skills nfl get_scoreboard
sports-skills nfl get_standings --season=2025
sports-skills nfl get_teams

Python SDK（代替手段）：

from sports_skills import nfl

scores = nfl.get_scoreboard({})
standings = nfl.get_standings({"params": {"season": "2025"}})

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

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

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

シーズンの選び方

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

• ユーザーがシーズンを指定している場合は、そのまま使用してください。
• 「現在のシーズン」「今シーズン」と言っている場合、または指定がない場合：NFL のシーズンは 9 月から 2 月までです。現在の月が 3 月から 8 月の場合は、season = current_year（次のシーズン）を使用してください。9 月から 2 月の場合、1 月または 2 月なら進行中のシーズンは前年に始まっており、それ以外なら現在の年に始まっています。

コマンド

コマンド	説明
get_scoreboard	NFL の試合のライブスコア／最近のスコア
get_standings	カンファレンス別、ディビジョン別の順位表
get_teams	NFL 全 32 チーム
get_team_roster	チームの全選手名簿
get_team_schedule	特定チームのスケジュール。データの提供範囲も報告します
get_game_summary	詳細なボックススコアと得点プレー
get_leaders	NFL の統計リーダー
get_news	NFL のニュース記事
get_play_by_play	試合の全プレー記録
get_win_probability	勝率チャートのデータ
get_schedule	1 シーズンの 1 週分、または ESPN の現在の対象期間。シーズン全体は取得できません
get_injuries	プロバイダー固有の ID、または未解決の ID を含む負傷者レポート
get_transactions	最近の移籍・契約取引
get_futures	フューチャーズ／オッズ市場
get_depth_chart	チームのデプスチャート
get_team_stats	チームの統計プロファイル
get_player_stats	選手の統計プロファイル
get_nflverse_schedule	nflverse ベースのスケジュール／結果テーブル（espn_event_id を含みます）
get_nflverse_weekly_rosters	nflverse ベースの週間選手名簿
get_nflverse_player_stats	nflverse ベースの選手統計。デフォルトではシーズン合計
get_nflverse_team_stats	nflverse ベースのチーム統計。デフォルトではシーズン合計
get_nflverse_play_by_play	nflverse ベースのプレーごとの記録
get_fantasy_trending	Sleeper のファンタジーで人気の追加／削除（人気度の件数、Sleeper の選手 ID）

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

空の get_schedule の応答からバイウィークだと推測してはいけません。coverage ブロックを確認してください。その完全性は unknown または partial であり、complete になることはありません。チームのシーズン全体を取得するには get_team_schedule を使用してください。ESPN のスコアボードはデータが混在し、切り詰められるため、シーズンのみを指定した get_schedule は拒否されます。負傷者情報が存在しない、または未解決であっても、選手が健康である証拠にはなりません。

Fantasy Trending（Sleeper）

get_fantasy_trending は、Sleeper の公開トレンドエンドポイントから、直近の期間に Sleeper のファンタジーリーグで最も追加（または削除）された NFL 選手を取得します。

sports-skills nfl get_fantasy_trending --trend_type=add --lookback_hours=24 --limit=10
sports-skills nfl get_fantasy_trending --trend_type=drop

• trend_type：add（デフォルト）または drop。lookback_hours：1～168 の整数時間（デフォルトは 24）。limit：1～100（デフォルトは 10）。
• count は、対象期間における選手の追加／削除数として Sleeper のトレンド API が報告する値です。これは人気の指標であり、予測値、ランキング、賭けに有利な情報ではありません。報告する際はその点を明記してください。
• 選手 ID は Sleeper 独自の名前空間に属する sleeper_player_id です。識別子としてそのまま使用してください。ESPN の選手 ID や nflverse の GSIS ID との対応付けはありません。対応付けを追加したり、別のプロバイダーの名前やチームとの一致を、同一選手であることが確認済みであるかのように示したりしないでください。
• name_resolved: false は、その ID に対応する名前が Sleeper の選手カタログに見つからなかったことを意味します。team と position は個別に解決されるため、値が入っている場合があります。カタログ自体を取得できなかった場合は、catalog_status が unavailable となり、その理由が warnings[] に記載されます。件数と ID は引き続き有効です。
• データの鮮度は source.trending_fetched_at で報告してください。トレンド結果は、同一プロセス内で 5 分間メモリにキャッシュされます。新しい CLI 呼び出しのたびに、結果が再取得されます。Sleeper の選手カタログ（ID、名前、チーム、ポジションのみに絞り込んだもの）も $XDG_CACHE_HOME/sports-skills/sleeper/（デフォルトは ~/.cache/...）に保存され、取得から 24 時間が経過するまではプロセスをまたいで再利用されます。これは、Sleeper がクライアントに対し、カタログの取得は 1 日に 1 回までとするよう求めているためです。このディスクキャッシュはベストエフォートです。書き込みに失敗しても呼び出しは成功し、次のプロセスではカタログが再取得されます。

nflverse の幅広い結果を整形する

nflverse のテーブルは列数が多く、get_nflverse_player_stats の 1 週間分だけでも約 960 行、100 列以上の統計項目（数百万文字）があります。すべての get_nflverse_* コマンドは sort_by、descending、limit、fields を受け付けるため、必要な行だけを取得できます。

# Week 5 passing leaders, 5 rows, 2 stat columns
sports-skills nfl get_nflverse_player_stats --season=2025 --week=5 --position=QB \
  --sort_by=passing_yards --limit=5 --fields=passing_yards,attempts

• sort_by：並べ替えに使用する列を 1 つ指定します。数値と数値文字列は数値として並べ替えられます。不足値は常に末尾になります。
• descending：true（デフォルト）または false。sort_by が指定されている場合のみ使用されます。
• limit：正の整数。並べ替え後に適用されます。
• fields：カンマ区切りの保持列リストです。以下の ID 列と sort_by 列は常に保持されます。
• 存在しない sort_by／fields 列を指定すると、有効な列の一覧を含むエラーが返されます。
• いずれかの項目を設定すると、レスポンスに total_rows（limit 適用前の一致行数）と returned_rows が追加されます。どれも設定しない場合、出力は変わりません。これらはデータ取得後に適用されるため、上流へのリクエストやそのリプレイエントリは変更されません。
• stats 内の統計列（例：passing_yards）は直接指定できます。fields では、選択したキーのみを含むオブジェクトとして stats が保持されます。

コマンド	fields で常に保持される列
get_nflverse_player_stats	player_id、player_name、position、team、week
get_nflverse_team_stats	team、season、week、game_id
get_nflverse_play_by_play	play_id、game_id
get_nflverse_weekly_rosters	player_id、player_name、team、position
get_nflverse_schedule	game_id、week、away_team、home_team

ESPN と nflverse の併用

2 つのバックエンドでは、異なる識別子システムを使用しています。get_nflverse_schedule は橋渡し役です。各イベントには espn_event_id が含まれており、これは ESPN のイベント ID と完全に一致します。

同じ試合について、nflverse の分析（EPA、勝利確率、ベッティングライン）と ESPN の詳細情報（ボックススコア、ドライブ）を組み合わせるには、次の手順を実行します。

1. get_nflverse_schedule(season=..., week=...) を呼び出します。
2. 対象のイベントから espn_event_id を読み取ります。
3. それを event_id として get_game_summary、get_play_by_play、または get_win_probability に渡します。

自動的には対応付けられない項目が 2 つあります。

• チーム略称。 ESPN では LAR と WSH、nflverse では LA と WAS を使用します。 get_nflverse_* 関数はどちらの略称も受け付け、変換します。逆方向 （nflverse → ESPN）の場合は、get_teams で対応するチームを特定します。
• 選手 ID。 ESPN のアスリート ID と nflverse の GSIS ID（00-0033873）には 関連性がなく、相互対応表もありません。名前とチームの組み合わせで照合してください。

スケジュールの行で注意するフィールド：total は実際に得点された合計ポイントで、 total_line はベッティングのオーバー／アンダーです。マーケット分析には total_line を使用してください。

例

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

1. get_scoreboard() を呼び出します 結果：スコアとステータスが含まれる、進行中および直近の NFL の全試合

例 2：カンファレンス順位 ユーザーの発言：「AFC の順位を見せて」 操作：

1. currentDate からシーズン年を導き出します
2. get_standings(season=<derived_year>) を呼び出します
3. AFC カンファレンスの結果に絞り込みます 結果：チームごとの W-L-T、PCT、PF、PA を含む AFC 順位表

例 3：チームのロースター ユーザーの発言：「Chiefs のロースターに誰がいる？」 操作：

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

例 4：スーパーボウルのボックススコア ユーザーの発言：「スーパーボウルはどうだった？」 操作：

1. get_schedule(week=23) を呼び出して、スーパーボウルの event_id を確認します
2. get_game_summary(event_id=<id>) を呼び出して、ボックススコア全体を取得します 結果：パス、ラッシング、レシーブの統計と得点プレーを含む完全なボックススコア

例 5：負傷者レポート ユーザーの発言：「Chiefs で負傷しているのは誰？」 操作：

1. get_injuries() を呼び出します
2. Kansas City Chiefs（team_id=12）の結果に絞り込みます 結果：選手名、ポジション、状態、負傷の種類を含む Chiefs の負傷者リスト

例 6：選手の統計 ユーザーの発言：「今シーズンの Patrick Mahomes の統計を見せて」 操作：

1. currentDate からシーズン年を導き出します
2. get_player_stats(player_id="3139477", season_year=<derived_year>) を呼び出します 結果：カテゴリごとのシーズン統計と、値、順位、試合あたりの平均

例 7：nflverse の週間ロースター ユーザーの発言：「データテーブルバックエンドから Week 1 の Chiefs のロースターを出して」 操作：

1. currentDate からシーズン年を導き出します
2. get_nflverse_weekly_rosters(season=<derived_year>, week=1, team="KC") を呼び出します 結果：チーム、選手、ポジション、背番号、状態が標準化された週間ロースターの行

例 8：nflverse のプレー・バイ・プレー ユーザーの発言：「Bills の Week 3 のプレー・バイ・プレーを取得して」 操作：

1. currentDate からシーズン年を導き出します
2. get_nflverse_play_by_play(season=<derived_year>, week=3, team="BUF") を呼び出します 結果：game_id、ダウン／距離、説明、EPA、WP／WPA、スコア状況を含むプレーの行

例 9：ファンタジーのウェイバー情報 ユーザーの発言：「今週、ファンタジーで誰が獲得されていますか？」 操作：

1. get_fantasy_trending(trend_type="add", lookback_hours=24, limit=10) を呼び出します
2. source.trending_fetched_at とともに、名前、チーム、ポジション、人数を報告します 結果：Sleeper で最も多く獲得された選手。推奨ではなく、Sleeper ユーザーの間での人気として説明します

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

• 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 を実行してください。PyPI にない場合は、GitHub からインストールしてください：pip install git+https://github.com/machina-sports/sports-skills.git

エラー：nflverse バックエンドを利用できません 原因：オプションの NFL バックエンド用エクストラがインストールされていません 解決策：sports-skills[nfl] をインストールして、nflverse プロバイダー（nflreadpy または互換性フォールバック）を利用できるようにしてください

エラー：ID でチームが見つかりません 原因：ESPN のチーム ID が間違っているか、古いものです 解決策：get_teams を呼び出して、ID 付きの現在の NFL 全 32 チーム一覧を取得してください

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

エラー：ポストシーズンの週番号で結果が返されません 原因：ポストシーズンでは、レギュラーシーズンとは異なる統一週番号（19～23）が使用されています 解決策：ワイルドカードには週 19、ディビジョナルには週 20、カンファレンスチャンピオンシップには週 21、スーパーボウルには週 23 を使用してください