football-data

Football Data

クエリを作成する前に、エンドポイント、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 キーは不要です。

クイックスタート

Python のインポートパスの問題を避けられるため、CLI を優先してください。

sports-skills football get_daily_schedule
sports-skills football get_season_standings --season_id=premier-league-2025

Python SDK（代替手段）：

from sports_skills import football

standings = football.get_season_standings(season_id="premier-league-2025")
schedule = football.get_daily_schedule()

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

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

• シーズン ID は get_current_season(competition_id="...") から取得してください。ハードコードしないでください。
• チーム ID は search_team(query="...") で解決し、数値の team_id として渡してください。get_head_to_head、get_team_strength、get_match_forecast では、必ず ID を渡してください。曖昧な名前（例：「Paris」というクラブが 2 つある場合）は、誤ったチームに解決されることがあります。
• 対象リーグがエンドポイントの対応範囲に含まれていることを確認してください。以下の対応範囲とソースマップを参照してください。ソースによって対応範囲は異なります。対応していないエンドポイントを呼び出すと、データではなく message を含む空のペイロードが返されます。
• get_event_xg と get_event_players_statistics（xG を含む）は、トップ 5 リーグ（EPL、La Liga、Bundesliga、Serie A、Ligue 1）に対してのみ呼び出してください。
• get_season_leaders と get_missing_players は、プレミアリーグのシーズンに対してのみ呼び出してください（season_id は premier-league- で始まる必要があります）。

シーズンの選び方

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

• ユーザーがシーズンを指定した場合：そのまま使用してください。
• ユーザーが「current」「latest」と指定した場合、またはシーズンを指定しなかった場合：get_current_season(competition_id="...") を呼び出して、アクティブな season_id を取得してください。年を推測したり、ハードコードしたりしないでください。
• シーズンの形式：常に {league-slug}-{year} です（例：2025-26 シーズンなら "premier-league-2025"）。年はシーズン終了年ではなく、開始年です。
• MLS の例外：MLS は同じ暦年内の春から秋に開催されます。get_current_season(competition_id="mls") を使用してください。

対応範囲とソースマップ

このスキルは複数の無料ソースを組み合わせています。対応範囲は一律ではありません。各エンドポイントが機能するのは、基盤となるソースにデータがある場合のみです。回答を約束する前に確認してください。エンドポイントが対応していない場合は、エラーではなく、説明の message を含む空のペイロードが返されます。そのメッセージを確認し、代替手段を使用してください。

エンドポイント	ソース	対応範囲
順位表、日程、チーム、試合の概要／ラインナップ／スタッツ／タイムライン	ESPN	すべてのリーグ（最も広範囲で、基盤となるソース）
get_event_xg、get_event_players_statistics（xG フィールド）	Understat	トップ 5 のみ（EPL、La Liga、Bundesliga、Serie A、Ligue 1）。RFPL は対象外です。Understat は対応を終了しました。Serie B と Championship も対象外です。
get_season_leaders、get_missing_players	FPL	プレミアリーグのみ
get_player_profile、get_season_transfers（市場価値）	Transfermarkt	tm_player_id がある任意の選手
get_head_to_head	football-data.co.uk	ヨーロッパの国内リーグ 12 件（EPL、Championship、La Liga、Serie A、Serie B、Bundesliga、Ligue 1、Eredivisie、Primeira Liga、スコットランド、ベルギー、トルコ）。同じディビジョン内の対戦のみ。
get_team_strength	ClubElo。利用できない場合はローカル Elo にフォールバック	ヨーロッパのクラブ（ロシアを含む）。ClubElo が停止している場合は、football-data.co.uk から算出したレーティングにフォールバックします。
get_match_forecast	ClubElo	ヨーロッパのクラブ（ロシアを含む）。フォールバックはありません。ClubElo の試合日程フィードが必要です。

目安：ESPN は「何が起きたか」をどこでも確認できます。Understat／FPL／ClubElo／football-data.co.uk などの補完ソースは、それぞれ対応範囲内でのみ情報を追加します。 試合日程とスコアの基準は常に ESPN です。補完ソースのスコアで ESPN のスコアを上書きしないでください。

（実運用テストで判明した注意点）

• get_team_profile はチームのメンバーを返します。 data.players[] には、ESPN の選手 ID、背番号、年齢を含む現在のロースターが格納されています。試合ごとに名前を集めるのではなく、こちらを使用してください。
• get_player_season_stats には、ほかのすべての機能と同じリーグスラッグを指定します（ESPN の bra.1 だけでなく、serie-a-brazil）。また、試合記録はシーズン合計ではなく、複数の大会を通じた直近約5試合分です。
• PK による得点はタイムラインでは penalty_goal です。 スコアと照合する際は、goal + penalty_goal + own_goal を数えてください。
• アディショナルタイムは added_time です。 45+2' のイベントは minute: 45, added_time: 2 となります（アディショナルタイム以外は 0）。
• 曖昧なチーム名ではなく、チーム ID を渡してください。 H2H／強さ／予測では、先に search_team でチームを特定し、数値の team_id を渡します。「Paris Saint-Germain」のような名前は、名前解決時に誤って別のクラブ（Paris FC）に紐付くことがあります。
• ClubElo のオフシーズンの欠落：現在の日付で get_team_strength を呼び出すと、夏季休止中のクラブが見つからないことがあります（クラブの週次 Elo 期間が今日まで続いていない場合があります）。よく知られたクラブが解決されない場合は、シーズン中の日付（例：date="2026-03-01"）を指定してください。
• ClubElo の障害：get_team_strength はローカルで計算した Elo にフォールバックし、source: "local-elo" を設定します。呼び出し間で数値を比較する前に、このフィールドを確認してください。ローカルの尺度はディビジョン単位のため、レーティングはそのディビジョン内でのみ意味があり、ディビジョンをまたぐ比較は拒否されます。フォールバックでは date が適用されます（その日時点のディビジョンをレーティングし、各エントリの as_of は集計対象となった最後の試合を示します）。get_match_forecast にはフォールバックがなく、空のままです。
• get_match_forecast の予測対象期間は短めです：ClubElo が予測するのは約1週間先までなので、試合日間やオフシーズンは空になります。これは想定どおりであり、障害ではありません。
• H2H は同じディビジョン内のみです：カップ戦や異なる階層で対戦した2クラブは表示されません。解決されたディビジョン内のリーグ戦が集計されます。
• H2H では「未解決」と「対戦経験なし」を区別します：football-data.co.uk では短い別名や略称（「FC Koln」、「M'gladbach」、「Sp Lisbon」）が使われています。teams[] 内の各クラブには resolved と matched_as が表示されます。クラブの resolved: false の場合、対戦数がゼロなのは検索に失敗したためであり、両クラブが一度も対戦していないという意味ではありません。

エンドポイントの組み合わせ（自由な組み合わせ）

複数の情報源を組み合わせて、より充実した回答を作成します。独立した呼び出しは並列で実行してください。

• 試合プレビュー（X vs Y）：search_team ×2 → get_head_to_head（直近の対戦成績）+ get_team_strength(team_id, team_id_2)（Elo の差／優勢なチーム）+ get_match_forecast（約1週間以内の場合：W/D/L + スコア予測）。トップ5リーグの試合には、直近の対戦に関する過去の get_event_xg の情報を追加してください。
• 試合レポート（試合後）：get_event_summary + get_event_statistics + get_event_timeline、トップ5リーグの場合は get_event_xg + get_event_players_statistics。
• チームの調子と背景情報：get_team_schedule（直近の結果）+ get_team_strength（現在の Elo と順位）+ get_missing_players（PL のみ）+ 試合ごとの get_event_xg（トップ5）。
• ライバル関係／ダービーの詳細分析：get_head_to_head（通算に近い対戦成績 + 得点）+ get_team_strength による現在の勢力比較。
• オッズの妥当性確認：get_match_forecast が無料のモデル基準値（W/D/L）を提示します。これを kalshi／polymarket のベッティングスキルと比較してください。

組み合わせの一部で情報を取得できない場合（例：トップ5以外の xG、MLS の H2H）は、その部分を何も言わずに省略し、取得できる情報を提示してください。情報源が1つ欠けていても、回答全体を中断しないでください。

コマンド

コマンド	説明
get_current_season	大会の現在のシーズンを検出します
get_competitions	現在のシーズン情報とともに、利用可能な大会を一覧表示します
get_competition_seasons	大会の利用可能なシーズンを表示します
get_season_schedule	シーズン全体の試合日程を表示します
get_season_standings	シーズンのリーグ順位表を表示します
get_season_leaders	得点ランキング／リーダー（Premier League のみ）を表示します
get_season_teams	シーズンのチームを表示します
search_team	チーム名で検索します
search_player	選手名で検索します
get_team_profile	チーム情報と現在の登録選手を表示します
get_daily_schedule	全リーグの指定日の全試合を表示します
get_event_summary	スコア付きの試合概要を表示します
get_event_lineups	試合のラインアップを表示します
get_event_statistics	試合のチーム統計を表示します
get_event_timeline	試合のタイムライン（ゴール、カード、交代）を表示します
get_team_schedule	特定チームの日程を表示します
get_head_to_head	過去の直接対決（H2H）の結果と統計（欧州国内リーグ）を表示します
get_team_strength	Elo レーティング／2 チームの比較（欧州クラブ）。ClubElo が停止している場合はローカル Elo にフォールバックします
get_match_forecast	ClubElo による勝ち・引き分け・負けの確率とスコア予測（約 1 週間先まで）を表示します
get_event_xg	xG データ（上位 5 リーグのみ）を表示します
get_event_players_statistics	xG を任意で含む、選手単位の試合統計を表示します
get_missing_players	負傷中／出場が不確かな選手（Premier League のみ）を表示します
get_season_transfers	Transfermarkt を通じて移籍履歴を表示します
get_player_season_stats	ESPN を通じて選手のシーズン統計を表示します
get_player_profile	選手プロフィール（FPL および／または Transfermarkt）を表示します

パラメーター一覧、戻り値の形式、データの網羅範囲をまとめた表については、references/api-reference.md を参照してください。

例

例 1：プレミアリーグの順位表 ユーザー：「プレミアリーグの順位表を見せて」 アクション：

1. get_current_season(competition_id="premier-league") を呼び出して、現在の season_id を取得します
2. get_season_standings(season_id=<season_id from step 1>) を呼び出します 結果：順位、チーム、試合数、勝利数、引き分け数、敗戦数、得失点差、勝ち点を含む順位表

例 2：試合レポート ユーザー：「アーセナル対リバプールの試合はどうだった？」 アクション：

1. get_daily_schedule() または get_team_schedule(team_id="359") を呼び出して、event_id を見つけます
2. get_event_summary(event_id="...") を呼び出して、スコアを取得します
3. get_event_statistics(event_id="...") を呼び出して、ボール支配率、シュート数などを取得します
4. get_event_xg(event_id="...") を呼び出して、xG を比較します（EPL — 上位 5 チームのみ） 結果：スコア、主要なスタッツ、xG を含む試合レポート

例 3：チームの詳細分析 ユーザー：「チェルシーの最近の調子を詳しく分析して」 アクション：

1. search_team(query="Chelsea") を呼び出します → team_id=363、competition=premier-league
2. get_team_schedule(team_id="363", competition_id="premier-league") を呼び出します → 直近の終了済み試合を見つけます
3. 直近の各試合について、get_event_xg、get_event_statistics、get_event_players_statistics を並行して呼び出します
4. get_missing_players(season_id=<season_id>) を呼び出します → チェルシーの負傷中・出場が不確かな選手に絞り込みます 結果：試合ごとの xG の推移、主要選手のスタッツ、負傷者レポート

例 4：選手の市場価値 ユーザー：「サカの市場価値はいくら？」 アクション：

1. get_player_profile(tm_player_id="433177") を呼び出して、Transfermarkt のデータを取得します
2. 必要に応じて fpl_id を追加して FPL のスタッツを取得します 結果：市場価値、価値の推移、移籍履歴

例 5：プレミアリーグ以外のクラブ ユーザー：「コリンチャンスについて教えて」 アクション：

1. search_team(query="Corinthians") を呼び出します → team_id=874、competition=serie-a-brazil
2. get_team_schedule(team_id="874", competition_id="serie-a-brazil") を呼び出して、試合日程を取得します
3. 直近の試合を選び、get_event_timeline(event_id="...") を呼び出して、ゴール、カード、交代を取得します 結果：試合日程、タイムラインのイベント（注：ブラジル・セリエAでは xG、FPL のスタッツ、シーズンのリーダー情報は利用できません）

例 6：試合のプレビュー（組み合わせて利用） ユーザー：「今週末のアーセナル対マンチェスター・シティをプレビューして」 アクション：

1. search_team(query="Arsenal") と search_team(query="Manchester City") を呼び出します → team_ids 359、382
2. 並行して、get_head_to_head(team_id="359", team_id_2="382")（直近の対戦成績とゴール数）、 get_team_strength(team_id="359", team_id_2="382")（Elo の差と優勢チーム）、 get_match_forecast(team_id="359", team_id_2="382")（勝敗予測と予想スコア。試合が約 1 週間以内の場合）を呼び出します
3. 調子・対戦成績と戦力差・モデル予測オッズをまとめます。空の結果が返された項目は省略します（例：試合まで 1 週間を超えている場合の予測）。 結果：過去の直接対決、現在の戦力、無料のモデル予測を組み合わせたプレビュー

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

• get_standings — 正しいコマンドは get_season_standings です（season_id が必要です）。
• get_live_scores — 利用できません。本日の試合には get_daily_schedule() を使用してください。
• get_team_squad / get_team_roster — get_team_profile を使用してください。data.players[] に ESPN の選手 ID を含む現在のロースターが格納されています（「注意点」を参照）。キャリアデータには、引き続き get_season_leaders と get_player_profile を使用してください。
• get_transfers — 正しいコマンドは get_season_transfers です（season_id と tm_player_ids が必要です）。
• get_match_results / get_match — event_id を指定して get_event_summary を使用してください。
• get_player_stats — 試合単位のスタッツには get_event_players_statistics を、キャリアデータには get_player_profile を使用してください。
• get_scores / get_results — event_id を指定して get_event_summary を使用してください。
• get_fixtures — 本日の試合には get_daily_schedule を、シーズン全体の日程には get_season_schedule を使用してください。
• get_league_table — season_id を指定して get_season_standings を使用してください。

上記のコマンド一覧にないコマンドは存在しません。一覧にないコマンドを試さないでください。

エラー処理

コマンドが失敗した場合（誤った event_id、データ不足、ネットワークエラーなど）、生のエラーをユーザーに表示しないでください。代わりに、次のようにします。

1. エラーを表に出さずに捕捉し、調査中の見つからなかったケースとして扱います。
2. 代替手段を試します。event_id からデータが返されない場合は、get_daily_schedule() または get_team_schedule() を呼び出して正しい ID を調べます。
3. 代替手段をすべて試した後にのみ、失敗を報告します。簡潔なメッセージを使用します（例：「該当する試合が見つかりませんでした。チーム名または日付を確認していただけますか？」）。

トラブルシューティング

エラー：sports-skills コマンドが見つかりません 原因：パッケージがインストールされていません 解決策：pip install sports-skills を実行します。PyPI にない場合は、GitHub からインストールします：pip install git+https://github.com/machina-sports/sports-skills.git

エラー：ModuleNotFoundError: No module named 'sports_skills' 原因：パッケージがインストールされていないか、パスに問題があります 解決策：パッケージをインストールします。パスの問題を避けるため、Python のインポートより CLI を優先してください

エラー：get_season_leaders または get_missing_players が PL 以外のリーグで空の結果を返します 原因：これらのコマンドはプレミアリーグでのみ動作し、他のリーグでは何も返さずに終了します 解決策：references/api-reference.md のデータ対応表を確認します。他のリーグでは、選手データに get_event_players_statistics を使用します

エラー：get_team_profile が選手を返しません 原因：指定したリーグのそのチーム ID に対して、ESPN にロースターがありません（誤った league_slug、または代表チーム／ユースチーム） 解決策：クラブが所属するリーグの league_slug を渡します（例：serie-a-brazil）。試合当日のメンバーには get_event_lineups を使用します

エラー：season_id の形式が正しくありません 原因：Season ID は {league-slug}-{year} 形式にする必要があります 解決策：get_current_season(competition_id="...") を使用して正しい形式を調べます。例："premier-league-2025"（"2025-2026" や "EPL-2025" ではありません）

エラー：最近の試合の xG データがありません 原因：試合終了後、Understat のデータ反映には 24～48 時間かかる場合があります 解決策：最近の上位 5 リーグの試合で get_event_xg が空の結果を返した場合は、後でもう一度試します。利用できるのは EPL、La Liga、Bundesliga、Serie A、Ligue 1 のみです

エラー：チームまたはイベント ID が不明です 原因：ID を検索せずに推測しました 解決策：search_team(query="team name") を使用してチーム ID を調べるか、get_daily_schedule／get_season_schedule を使用してイベント ID を調べます。ID を推測しないでください。