mlb-data

MLB 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 mlb get_scoreboard
sports-skills mlb get_standings --season=2025
sports-skills mlb get_teams

重要：クエリを実行する前に必ず確認してください

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

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

シーズンの選択

暦年だけでなく、システムプロンプトの日付から現在のシーズンを導き出してください。

• ユーザーがシーズンを指定した場合は、そのまま使用してください。
• ユーザーが「現在の」「今シーズン」などと指定した場合、またはシーズンを指定していない場合：MLB のシーズンは 3 月下旬／4 月から 10 月までです。現在の月が 1 月～3 月の場合、直近で終了したシーズンは前年です。4 月以降は現在の暦年を使用してください。

コマンド

コマンド	説明
get_scoreboard	MLB のライブ／最近のスコア
get_standings	リーグおよび地区別の順位
get_teams	MLB の全 30 チーム
get_team_roster	チームの全ロースター
get_team_schedule	特定チームのスケジュール
get_game_summary	詳細なボックススコアと得点プレー
get_leaders	MLB の統計リーダー
get_news	MLB のニュース記事
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_mlb_player	名前で MLB の選手登録情報を検索
get_mlbstats_schedule	MLB Stats API 経由の試合情報。1901 年まで遡る履歴があり、gamePk ID を含む
get_mlbstats_player_stats	MLB Stats API 経由の統計グループ別のシーズン／通算／年度別スプリット。stat_type=game_log では試合ごとに 1 件のスプリットを取得
get_mlbstats_play_by_play	投球単位のプレー経過（球速、回転数、ホームベース上の座標、打球速度、打ち出し角度）
get_mlbstats_boxscore	MLB Stats API 経由の、選手ごとの打撃／投球成績を含む完全なボックススコア
get_mlbstats_standings	MLB Stats API 経由の地区別順位
get_mlbstats_leaders	MLB Stats API 経由の、任意の統計カテゴリのリーグリーダー

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

プレー経過の結果の整形

get_mlbstats_play_by_play と get_mlbstats_player_stats は、sort_by、descending、limit、fields を受け付けます。 打席結果だけが必要な場合は、fields を使うのが投球ごとのリストを取り除く最も手早い方法です：

sports-skills mlb get_mlbstats_play_by_play --game_pk=775296 --fields=event,rbi

• sort_by：並べ替えに使う列を 1 つ指定します。数値（および数値文字列）は数値として並べ替えられ、欠損値は常に最後になります。
• descending：true（デフォルト）または false。sort_by と併用した場合のみ使用されます。
• limit：正の整数。並べ替え後に適用されます。
• fields：カンマ区切りの保持対象リスト。inning、half、batter、pitcher（プレー経過の場合）、または season、team、game_pk、game_date（選手統計の場合。homeRuns などの統計キーは直接指定可能）と、sort_by 列は常に保持されます。
• 存在しない sort_by／fields 列を指定すると、有効な列の一覧を示すエラーが返されます。
• いずれかを設定すると、レスポンスに total_rows（limit 適用前の該当行数）と returned_rows が追加されます。どれも設定しない場合、出力は変更されません。これらはデータ取得後に適用されるため、上流へのリクエストやその再生エントリーは変わりません。

ESPN と MLB Stats API の併用

get_mlbstats_* コマンドは、MLB 独自のオープン API である statsapi.mlb.com のデータを読み取ります。この API には、ESPN にはない分析データが含まれます。投球ごとの球速・回転数・位置、インプレー打球の打球速度と打球角度、統計グループ別の通算成績、そして 1901 年までさかのぼる日程などです。2 つのデータソースでは、互換性のない ID システムが使われています。

• 試合 ID。 MLB では gamePk（例：775296）、ESPN ではイベント ID（例：401570367）を使います。共通の列はないため、試合日とチームで結合します。
• チーム略称。 2 チームで表記が異なります。ESPN の ARI／CHW に対し、MLB では AZ／CWS です。すべての get_mlbstats_* のチームフィルターはどちらの表記も受け付け、行には両方の値（team_abbreviation、team_abbreviation_espn）が含まれます。
• 選手 ID。 MLB の人物 ID（660271）と ESPN の選手 ID に関連性はありません。find_mlb_player で名前を検索できます。アクセント記号のない表記でも一致します（「acuna」で「Ronald Acuña Jr.」が見つかります）。
• 延期された試合は重複します。 get_mlbstats_schedule では、延期または中断された試合が、同じ game_pk の下に 2 回掲載されます。元の日程には rescheduled: true（および rescheduled_to）が、振替日には rescheduled_from が設定されます。試合数を数える際は rescheduled の行を除外してください。
• 日程の時刻。 start_time は UTC です。venue_timezone は球場の IANA タイムゾーン（例：America/New_York。MLB が省略した場合は null）で、local_date は MLB 公式の（現地）日付です。
• ポストシーズンの game_type フィルターは日付で絞り込みます。 ワールドシリーズ以外の日付で game_type="worldseries" を指定すると、試合は返されず、warnings に項目が追加されます。game_type を省略するか、team と season を併せて指定して、そのラウンドの日付を一覧表示してください。
• リーダーはグループごとにまとめられます。 homeRuns のようなカテゴリは、打撃、捕手、投手（被本塁打）に存在します。行には stat_group のラベルが付くため、1 つだけ取得する場合は stat_group= を指定してください。

レスポンスには、API からそのまま引き継いだ MLB の copyright 表記が含まれます。

例

例 1：今日のスコア ユーザーの発言：「今日の MLB の試合結果は？」 アクション：

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

例 2：地区順位 ユーザーの発言：「AL East の順位を見せて」 アクション：

1. currentDate からシーズンの年を導き出します
2. get_standings(season=<derived_year>) を呼び出します
3. 結果を American League East に絞り込みます 結果：勝敗数、勝率、首位との差、得失点差を含む AL East の順位

例 3：チームのロースター ユーザーの発言：「ヤンキースのロースターには誰がいる？」 アクション：

1. get_team_roster(team_id="10") を呼び出します 結果：名前、ポジション、左右の打投、身長、体重を含むヤンキースの全ロースター

例 4：試合のボックススコア ユーザーの発言：「昨夜のドジャースの試合の完全なボックススコアを見せて」 アクション：

1. get_scoreboard(date="<yesterday>") を呼び出して event_id を探します
2. get_game_summary(event_id=<id>) を呼び出して完全なボックススコアを取得します 結果：選手ごとの打撃・投球成績を含む完全なボックススコア

例 5：負傷者リスト ユーザーの発言：「ヤンキースで IL に入っているのは誰？」 アクション：

1. get_injuries() を呼び出します
2. 結果を New York Yankees（team_id=10）に絞り込みます 結果：選手名、ポジション、IL の種類、負傷の詳細を含むヤンキースの IL リスト

例 6：選手の成績 ユーザーの発言：「大谷翔平の成績を見せて」 アクション：

1. currentDate からシーズンの年を導き出します
2. get_player_stats(player_id="39832", season_year=<derived_year>) を呼び出します 結果：カテゴリー（打撃、投球）別のシーズン成績。数値、順位、1 試合あたりの平均を含みます

例 7：ワールドシリーズの優勝予想 ユーザーの発言：「ワールドシリーズの優勝候補は？」 アクション：

1. get_futures(limit=10) を呼び出します 結果：オッズ値を含むワールドシリーズの有力候補上位

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

• 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 を含む MLB の全 30 チームの最新一覧を取得してください

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

エラー：オフシーズン — スコアボードに 0 件のイベントが返されます 原因：オフシーズン（11 月～3 月）には試合が予定されていません 解決策：代わりに get_standings または get_news を使用してください。MLB のオフシーズン中の移籍情報は get_transactions で確認できます