football-data

フットボールデータ

セットアップ

初めて使用する前に、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()

シーズンの選択

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

• ユーザーがシーズンを指定した場合は、そのまま使用します。
• ユーザーが「現在の」「最新の」と言った場合、または指定しなかった場合：get_current_season(competition_id="...") を呼び出して、有効な season_id を取得します。年を推測したり、ハードコードしたりしないでください。
• シーズンの形式：常に {league-slug}-{year} を使用します（例：2025-26 シーズンの場合は "premier-league-2025"）。年はシーズンの終了年ではなく、開始年です。
• MLS の例外：MLS は暦年内の春から秋に開催されます。get_current_season(competition_id="mls") を使用してください。MLS が欧州の暦に従うと想定しないでください。
• season_id をハードコードしないでください。 常に get_current_season() またはシステムの日付から導き出してください。

リーグ別のデータ範囲

すべてのリーグで、すべてのデータを利用できるわけではありません。リーグに応じて適切なコマンドを使用してください。

コマンド	全 13 リーグ	上位 5 リーグのみ	PL のみ
get_season_standings	x
get_daily_schedule	x
get_season_schedule	x
get_season_teams	x
search_team	x
get_team_schedule	x
get_team_profile	x
get_event_summary	x
get_event_lineups	x
get_event_statistics	x
get_event_timeline	x
get_current_season	x
get_competitions	x
get_event_xg		x
get_event_players_statistics (with xG)		x
get_season_leaders			x
get_missing_players			x

上位 5 リーグ（Understat）：EPL、La Liga、Bundesliga、Serie A、Ligue 1。 PL のみ（FPL）：Premier League — 負傷情報、選手統計、保有率、ICT インデックス。 全リーグ：ESPN 経由で、スコア、順位表、日程、試合概要、ラインナップ、チーム統計を利用できます。 Transfermarkt：tm_player_id がある選手なら誰でも利用できます — 市場価値と移籍履歴を取得できます。

注：MLS は異なるシーズン構造（暦年内の春から秋）を採用しています。適切な season_id を特定するには、get_current_season(competition_id="mls") を使用してください。

ID の規則

• season_id：{league-slug}-{year}（例："premier-league-2025"、"la-liga-2025"）
• competition_id：リーグのスラッグ（例："premier-league"、"serie-a"、"champions-league"）
• team_id：ESPN チーム ID（数値文字列）（例："359"（Arsenal）、"86"（Real Madrid））
• event_id：ESPN イベント ID（数値文字列）（例："740847"）
• fpl_id：FPL 要素 ID またはコード（PL の選手のみ）
• tm_player_id：Transfermarkt 選手 ID（例："433177"（Saka）、"342229"（Mbappe））

コマンド

get_current_season

大会の現在のシーズンを特定します。すべてのリーグで使用できます。

• competition_id（str、必須）：大会のスラッグ

data.competition と data.season を返します：

{"competition": {"id": "premier-league", "name": "Premier League"}, "season": {"id": "premier-league-2025", "name": "2025-26 English Premier League", "year": "2025"}}

get_competitions

現在のシーズン情報とともに、利用可能な大会を一覧表示します。パラメーターはありません。すべてのリーグで使用できます。

id、name、code、current_season を含む data.competitions[] を返します。

get_competition_seasons

大会で利用可能なシーズンを取得します。すべてのリーグで使用できます。

• competition_id（str、必須）：大会のスラッグ

get_season_schedule

シーズン全体の試合日程を取得します。すべてのリーグで使用できます。

• season_id（str、必須）：シーズンのスラッグ（例："premier-league-2025"）

data.schedules[] を返します。以下のイベントと同じ形式です。

get_season_standings

シーズンのリーグ順位表を取得します。すべてのリーグで使用できます。

• season_id（str、必須）：シーズンのスラッグ

data.standings[].entries[] を返します：

{
  "position": 1,
  "team": {"id": "359", "name": "Arsenal", "short_name": "Arsenal", "abbreviation": "ARS", "crest": "https://..."},
  "played": 26, "won": 17, "drawn": 6, "lost": 3,
  "goals_for": 50, "goals_against": 18, "goal_difference": 32, "points": 57
}

get_season_leaders

シーズンの得点ランキング／リーダーを取得します。Premier League のみ（FPL 経由）。

• season_id (str, required): シーズンのスラッグ（premier-league-* である必要があります）

data.leaders[] を返します。選手名は .player.name の下にネストされている点に注意してください。

{
  "player": {"id": "223094", "name": "Erling Haaland", "first_name": "Erling", "last_name": "Haaland", "position": "Forward"},
  "team": {"id": "43", "name": "Man City"},
  "goals": 22, "assists": 6, "penalties": 0, "played_matches": 25
}

PL 以外のリーグでは空を返します。

get_season_teams

シーズンのチームを取得します。すべてのリーグに対応しています。

• season_id (str, required): シーズンのスラッグ

search_team

すべてのリーグ（または特定のリーグ）からチームを名前で検索します。あいまい一致を使用します。

• query (str, required): 検索するチーム名（例："Corinthians"、"Barcelona"、"Man Utd"）
• competition_id (str, optional): 検索対象を1つのリーグに限定します（例："serie-a-brazil"、"premier-league"）

一致したチームごとに、team、competition、season を含む data.results[] を返します。

{"team": {"id": "874", "name": "Corinthians"}, "competition": {"id": "serie-a-brazil", "name": "Serie A Brazil"}, "season": {"id": "serie-a-brazil-2025", "year": "2025"}}

get_team_profile

チームの基本情報（名前、エンブレム、スタジアム）を取得します。チームの選手一覧／登録選手は返しません。PL の選手 ID を調べるには get_season_leaders を使用し、個々の選手情報を取得するには get_player_profile を使用してください。

• team_id (str, required): ESPN のチーム ID
• league_slug (str, optional): リーグのヒント（解決を高速化します）

data.team と data.venue を返します。data.players[] は空です。推奨されるワークフローについては、以下の「PL チームを詳しく調べる」例を参照してください。

get_daily_schedule

特定の日付について、すべてのリーグの試合を取得します。

• date (str, optional): YYYY-MM-DD 形式の日付。デフォルトは今日です。

data.date と data.events[] を返します。

{
  "id": "748381", "status": "not_started", "start_time": "2026-02-16T20:00Z",
  "competition": {"id": "la-liga", "name": "La Liga"},
  "season": {"id": "la-liga-2025", "year": "2025"},
  "venue": {"name": "Estadi Montilivi", "city": "Girona"},
  "competitors": [
    {"team": {"id": "9812", "name": "Girona", "abbreviation": "GIR"}, "qualifier": "home", "score": 0},
    {"team": {"id": "83", "name": "Barcelona", "abbreviation": "BAR"}, "qualifier": "away", "score": 0}
  ],
  "scores": {"home": 0, "away": 0}
}

ステータスの値："not_started"、"live"、"halftime"、"closed"、"postponed"。

get_event_summary

スコア付きの試合概要を取得します。すべてのリーグに対応しています。

• event_id (str, required): 試合／イベント ID

data.event を返します（デイリースケジュールのイベントと同じ形式です）。

get_event_lineups

試合のラインナップを取得します。すべてのリーグに対応しています（ESPN で利用可能な場合）。

• event_id (str, required): 試合／イベント ID

data.lineups[] を返します。

{
  "team": {"id": "364", "name": "Liverpool", "abbreviation": "LIV"},
  "qualifier": "home",
  "formation": "4-3-3",
  "starting": [{"id": "275599", "name": "Caoimhín Kelleher", "position": "Goalkeeper", "shirt_number": 1}],
  "bench": [{"id": "...", "name": "...", "position": "...", "shirt_number": 62}]
}

get_event_statistics

試合のチーム統計を取得します。すべてのリーグに対応しています。

• event_id (str, required): 試合／イベント ID

data.teams[] を返します。

{
  "team": {"id": "244", "name": "Brentford"},
  "qualifier": "home",
  "statistics": {"ball_possession": "40.8", "shots_total": "10", "shots_on_target": "3", "fouls": "12", "corners": "4"}
}

get_event_timeline

試合のタイムライン／主要イベント（ゴール、カード、交代）を取得します。すべてのリーグに対応しています。

• event_id (str, required): 試合／イベント ID

ゴール、カード、交代のイベントを含む data.timeline[] を返します。

get_team_schedule

特定のチームのスケジュールを取得します。過去の試合結果と今後の試合の両方が含まれます。すべてのリーグに対応しています。

• team_id (str, required): ESPN のチーム ID
• league_slug (str, optional): リーグのヒント（解決を高速化します）
• season_year (str, optional): シーズン年のフィルター
• competition_id (str, optional): 結果を1つの大会に限定します（例："serie-a-brazil"、"premier-league"）

get_head_to_head

利用不可 — ライセンスされたデータが必要です。このコマンドは呼び出さないでください。空の結果が返されます。代わりに、両チームについて get_team_schedule を使用し、重複する試合を手動で絞り込んでください。

• team_id (str, required): 1つ目のチーム ID
• team_id_2 (str, required): 2つ目のチーム ID

get_event_xg

Understat の期待ゴール（xG）データを取得します。トップ5リーグのみ：EPL、La Liga、Bundesliga、Serie A、Ligue 1。その他のリーグでは空を返します。

• event_id (str, required): 試合／イベント ID

data.teams[] と data.shots[] を返します。

{"team": {"id": "244", "name": "Brentford"}, "qualifier": "home", "xg": 1.812}

data.shots[] には、シュートごとの xG を含む個別のシュートデータが格納されます。注意：直近の試合（過去24〜48時間）は、まだ Understat にインデックスされていない場合があります。

get_event_players_statistics

xG の拡張情報を含む、選手ごとの試合統計を取得します。すべてのリーグに対応しています（基本統計は ESPN から取得）。xG／xA の拡張情報はトップ5リーグのみ（Understat）です。

• event_id (str, required): 試合／イベント ID

data.teams[].players[] を返します。

{
  "id": "...", "name": "Bukayo Saka", "position": "Midfielder", "shirt_number": 7, "starter": true,
  "statistics": {"appearances": "1", "shotsTotal": "3", "shotsOnTarget": "1", "foulsCommitted": "1", "xg": "0.45", "xa": "0.12"}
}

xg と xa フィールドはトップ5リーグでのみ存在します。

get_missing_players

負傷中／離脱中／出場が不確実な選手を取得します。プレミアリーグのみ（FPL 経由）。それ以外のリーグでは空の結果を返します。

• season_id（str、必須）：シーズンスラッグ（premier-league-* である必要があります）

data.teams[].players[] を返します：

{
  "id": "463748", "name": "Mikel Merino Zazón", "web_name": "Merino",
  "position": "Midfielder", "status": "injured",
  "news": "Foot injury - Unknown return date",
  "chance_of_playing_this_round": 0, "chance_of_playing_next_round": 0
}

ステータス値：「injured」、「unavailable」、「doubtful」、「suspended」。

get_season_transfers

Transfermarkt 経由で特定の選手の移籍履歴を取得します。すべてのリーグに対応しています。

• season_id（str、必須）：シーズンスラッグ（年による移籍の絞り込みに使用）
• tm_player_ids（list、必須）：Transfermarkt の選手 ID

data.transfers[] を返します：

{
  "player_tm_id": "433177", "date": "2019-07-01", "season": "19/20",
  "from_team": {"name": "Arsenal U23", "image": "https://..."},
  "to_team": {"name": "Arsenal", "image": "https://..."},
  "fee": "-", "market_value": "-"
}

get_player_season_stats

ESPN の概要エンドポイント経由で選手のシーズン統計を取得します。ESPN の選手 ID があるリーグに対応しています。

• player_id（str、必須）：ESPN の選手 ID
• league_slug（str、任意）：リーグスラッグのヒント（例：「eng.1」、「esp.1」）。デフォルトでは自動検出します。

シーズン統計（ゴール、アシスト、出場数など）と、利用可能な場合は試合ログを返します。

get_player_profile

選手のプロフィールを取得します。Transfermarkt ID または FPL ID があれば、どの選手にも対応しています。少なくとも 1 つの ID が必要です。

• fpl_id（str、任意）：FPL の選手 ID（プレミアリーグの選手のみ）
• tm_player_id（str、任意）：Transfermarkt の選手 ID（すべてのリーグ）

tm_player_id を指定すると、次の内容を含む data.player を返します：

{
  "market_value": {"value": 130000000, "currency": "EUR", "formatted": "€130.00m", "date": "09/12/2025", "age": "24", "club": "Arsenal FC"},
  "market_value_history": [{"value": 7000000, "formatted": "€7.00m", "date": "23/09/2019", "club": "Arsenal FC"}],
  "transfer_history": [
    {"player_tm_id": "433177", "date": "2019-07-01", "season": "19/20", "from_team": {"name": "Arsenal U23"}, "to_team": {"name": "Arsenal"}, "fee": "-"}
  ]
}

fpl_id を指定すると、FPL の統計（ポイント、調子、ICT インデックス、保有率など）を含む data.player.fpl_data も返します。

対応リーグ

プレミアリーグ、ラ・リーガ、ブンデスリーガ、セリエ A、リーグ・アン、MLS、チャンピオンシップ、エールディヴィジ、プリメイラ・リーガ、ブラジル・セリエ A、チャンピオンズリーグ、欧州選手権、ワールドカップ。

データソース

ソース	提供データ	対応リーグ
ESPN	スコア、順位表、日程、ラインナップ、試合統計、タイムライン	13 リーグすべて
openfootball	日程、順位表、チーム一覧（ESPN が利用できない場合のフォールバック）	10 リーグ（CL、欧州選手権、ワールドカップを除くすべて）
Understat	試合ごとの xG、シュートごとの xG、選手の xG／xA	上位 5 リーグ（EPL、ラ・リーガ、ブンデスリーガ、セリエ A、リーグ・アン）
FPL	得点ランキング上位、負傷情報、選手統計、保有率	プレミアリーグのみ
Transfermarkt	市場価値、移籍履歴	任意の選手（tm_player_id が必要）

すべてのスポーツを網羅した、ライセンス取得済みのデータ（Sportradar、Opta、Genius Sports）については、Machina Sports をご覧ください。

例

ユーザー：「プレミアリーグの順位表を見せて」

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

ユーザー：「アーセナル対リバプールの試合はどうなった？」

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チームのみ）
5. スコア、主要なスタッツ、xG を含む試合レポートを提示します

ユーザー：「チェルシーの最近の調子を詳しく教えて」

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(event_id="...") を呼び出して、xG 比較とシュートマップを取得します
   • get_event_statistics(event_id="...") を呼び出して、ボール支配率、シュート数、パス数を取得します
   • get_event_players_statistics(event_id="...") を呼び出して、選手個人の xG/xA を取得します
4. get_missing_players(season_id=<season_id>) を呼び出します → チェルシーの負傷中または出場が不確かな選手に絞り込みます
5. get_season_leaders(season_id=<season_id>) を呼び出します → チェルシーの選手に絞り込み、各選手の FPL ID を取得します
6. 主力選手について get_player_profile(fpl_id="...", tm_player_id="...") を呼び出します — FPL のスタッツ（調子、保有率、ICT）と Transfermarkt のデータ（市場価値、移籍履歴）を組み合わせます
7. 試合ごとの xG の推移、主力選手のスタッツ、負傷者情報、市場価値を提示します

ユーザー：「サカの市場価値はいくら？」

1. Transfermarkt のデータを取得するため、get_player_profile(tm_player_id="433177") を呼び出します
2. プレミアリーグの選手であれば、必要に応じて FPL のスタッツを取得するために fpl_id を追加します
3. 市場価値、価値の推移、移籍履歴を提示します

ユーザー：「コリンチャンスについて教えて」

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="...") を呼び出します
4. 注：ブラジルのセリエAでは、xG、FPL のスタッツ、シーズンリーダーは利用できません

エラー処理

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

1. エラーを表に出さずに処理する — 失敗は致命的なエラーではなく、探索中に見つからなかったものとして扱います。
2. 代替手段を試す — たとえば、event_id からデータを取得できない場合は、get_daily_schedule() または get_team_schedule() を呼び出して正しい ID を探します。ESPN が停止している場合でも、get_season_standings または get_season_schedule から openfootball のデータを取得できることがあります。
3. 代替手段をすべて試してから失敗を報告する — その際は、トレースバックや未加工の CLI 出力ではなく、「その試合が見つかりませんでした。チーム名や日付を確認していただけますか？」のように、わかりやすいメッセージで伝えます。

これは特に、未加工の実行エラーが不具合のように見えてしまう Telegram や Slack などのメッセージングプラットフォームを介してエージェントが応答する場合に重要です。

よくある間違い

有効なコマンドは次のものだけです。 コマンド名を作ったり、推測したりしないでください。

• get_current_season
• get_competitions
• get_competition_seasons
• get_season_schedule
• get_season_standings
• get_season_leaders
• get_season_teams
• search_team
• 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
• get_event_xg
• get_event_players_statistics
• get_missing_players
• get_season_transfers
• get_player_profile
• get_player_season_stats

存在しないコマンド（よく幻覚されるもの）：

• get_standings — 正しいコマンドは get_season_standings です（season_id が必要です）。
• get_live_scores — 利用できません。今日の試合には get_daily_schedule() を使用してください。進行中の試合は、ステータスフィールドに「live」と表示されます。
• get_team_squad / get_team_roster — get_team_profile は選手を返しません。PL 選手の 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 を使用してください。

その他のよくある間違い：

• PL 以外のリーグで get_season_leaders や get_missing_players を使用する — 結果は空になります。データカバレッジ表を確認してください。
• 上位 5 リーグ以外で get_event_xg を使用する — 結果は空になります。EPL、La Liga、Bundesliga、Serie A、Ligue 1 のみで動作します。
• search_team、get_daily_schedule、または get_season_schedule で調べずに team_id や event_id を推測する。

コマンドが存在するかどうかわからない場合は、このリストを確認してください。上記にないコマンドは試さないでください。

トラブルシューティング

• sports-skills コマンドが見つからない：パッケージがインストールされていません。pip install sports-skills を実行してください。PyPI でパッケージが見つからない場合は、GitHub からインストールしてください：pip install git+https://github.com/machina-sports/sports-skills.git。Python 3.10 以降が必要です — セットアップのセクションを参照してください。
• ModuleNotFoundError: No module named 'sports_skills'：上記と同様です — パッケージをインストールしてください。パスの問題を避けるため、Python のインポートより CLI を優先してください。
• 他のリーグで PL 専用コマンドを使用すると結果が空になる：get_season_leaders と get_missing_players は Premier League のデータのみを返します。他のリーグでは何も表示せずに空の結果を返すため、データカバレッジ表を確認してください。
• get_team_profile が選手を返さない：これは想定どおりです — 選手名簿は利用できません。PL チームの選手データを取得するには、get_season_leaders を使用して選手とその FPL ID を調べてから、詳細な統計には get_player_profile(fpl_id="...") を使用してください。Transfermarkt のデータには、選手の tm_player_id が必要です。
• FPL ID と Transfermarkt ID の検索：get_season_leaders(season_id="premier-league-2025") を使用して、PL 選手の FPL ID を調べてください。Transfermarkt ID は transfermarkt.com で確認する必要があります — ID は選手の URL の末尾にある数字です。よく知られている例：Cole Palmer = 568177、Bukayo Saka = 433177、Mbappe = 342229。
• 最近の試合の xG がない：Understat のデータは、試合終了後 24～48 時間ほど遅れる場合があります。上位 5 リーグの最近の試合で get_event_xg の結果が空の場合は、しばらくしてから再度試してください。
• season_id の形式が誤っている：{league-slug}-{year} の形式である必要があります。例："premier-league-2025"。"2025-2026" や "EPL-2025" ではありません。正しい形式を確認するには get_current_season() を使用してください。
• チーム ID またはイベント ID が不明：search_team(query="team name") を使用して名前からチーム ID を検索するか、get_season_teams を使用してシーズン内のすべてのチームを一覧表示してください。イベント ID を見つけるには get_daily_schedule または get_season_schedule を使用してください。ID は ESPN の数値文字列です。