football-data

仓库: machina-sports/sports-skills
安装量: 294
排名: #3075

安装

npx skills add https://github.com/machina-sports/sports-skills --skill football-data

Football Data Setup Before first use, check if the CLI is available: which sports-skills || pip install sports-skills If pip install fails (package not found or Python version error), install from GitHub: pip install git+https://github.com/machina-sports/sports-skills.git The package requires Python 3.10+. If your default Python is older, use a specific version: 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

No API keys required.
Quick Start
Prefer the CLI — it avoids Python import path issues:
sports-skills football get_daily_schedule
sports-skills football get_season_standings
--season_id
=
premier-league-2025
Python SDK (alternative):
from
sports_skills
import
football
standings
=
football
.
get_season_standings
(
season_id
=
"premier-league-2025"
)
schedule
=
football
.
get_daily_schedule
(
)
Choosing the Season
Derive the current year from the system prompt's date (e.g.,
currentDate: 2026-02-16
→ current year is 2026).
If the user specifies a season
, use it as-is.
If the user says "current", "latest", or doesn't specify
Call
get_current_season(competition_id="...")
to get the active season_id. Do NOT guess or hardcode the year.
Season format
Always
{league-slug}-{year}
(e.g.,
"premier-league-2025"
for the 2025-26 season). The year is the start year of the season, not the end year.
Never hardcode a season_id.
Always derive it via
get_current_season()
or from the system date.
Calendar-year vs European leagues
Two season formats exist — choose the right mental model for the league:
Format
Leagues
Season window
Example (current year 2026)
Calendar-year (
jan
)
Serie A Brazil, MLS, J-League, Liga Argentina, A-League, NWSL
Runs within a single calendar year (~Jan-Dec)
serie-a-brazil-2026
European (
aug
)
Premier League, La Liga, Bundesliga, Serie A, Ligue 1, Championship, Eredivisie, Primeira Liga, Champions League, etc.
Runs Aug of year N to May/Jun of year N+1
premier-league-2025
(the 2025-26 season)
Calendar-year leagues start early in the year.
The Brazilian Serie A, MLS, J-League, and Argentine Liga typically begin between January and April. Do NOT assume they follow the European calendar. If it's March 2026, the Brasileirão 2026 is likely already underway.
Fallback behavior
When ESPN is temporarily unavailable,
get_current_season
returns a date-based estimate (marked with
"estimated": true
). This estimate is reliable — use it normally. The season_id it returns is valid for other commands like
get_season_standings
.
Data Coverage by League
Not all data is available for every league. Use the right command for the right league.
Command
All 13 leagues
Top 5 only
PL only
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
Top 5 leagues
(Understat): EPL, La Liga, Bundesliga, Serie A, Ligue 1.
PL only
(FPL): Premier League — injury news, player stats, ownership, ICT index.
All leagues
via ESPN — scores, standings, schedules, match summaries, lineups, team stats.
Transfermarkt
Works for any player with a
tm_player_id
— market values and transfer history.
Note
MLS uses a different season structure (spring-fall calendar). Use
get_current_season(competition_id="mls")
to detect the right season_id.
ID Conventions
season_id
:
{league-slug}-{year}
e.g.
"premier-league-2025"
,
"la-liga-2025"
competition_id
league slug e.g.
"premier-league"
,
"serie-a"
,
"champions-league"
team_id
ESPN team ID (numeric string) e.g.
"359"
(Arsenal),
"86"
(Real Madrid)
event_id
ESPN event ID (numeric string) e.g.
"740847"
fpl_id
FPL element ID or code (PL players only)
tm_player_id
Transfermarkt player ID e.g.
"433177"
(Saka),
"342229"
(Mbappe)
Commands
get_current_season
Detect current season for a competition. Works for all leagues.
competition_id
(str, required): Competition slug
Returns
data.competition
and
data.season
:
{
"competition"
:
{
"id"
:
"premier-league"
,
"name"
:
"Premier League"
}
,
"season"
:
{
"id"
:
"premier-league-2025"
,
"name"
:
"2025-26 English Premier League"
,
"year"
:
"2025"
}
}
get_competitions
List available competitions with current season info. No params. Works for all leagues.
Returns
data.competitions[]
with
id
,
name
,
code
,
current_season
.
get_competition_seasons
Get available seasons for a competition. Works for all leagues.
competition_id
(str, required): Competition slug
get_season_schedule
Get full season match schedule. Works for all leagues.
season_id
(str, required): Season slug (e.g., "premier-league-2025")
Returns
data.schedules[]
— same shape as events below.
get_season_standings
Get league table for a season. Works for all leagues.
season_id
(str, required): Season slug
Returns
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
Get top scorers/leaders for a season.
Premier League only
(via FPL).
season_id
(str, required): Season slug (must be
premier-league-*
)
Returns
data.leaders[]
— note: player name is nested under
.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
}
Returns empty for non-PL leagues.
get_season_teams
Get teams in a season. Works for all leagues.
season_id
(str, required): Season slug
search_team
Search for a team by name across all leagues (or a specific one). Uses fuzzy matching.
query
(str, required): Team name to search (e.g., "Corinthians", "Barcelona", "Man Utd")
competition_id
(str, optional): Limit search to one league (e.g., "serie-a-brazil", "premier-league")
Returns
data.results[]
with
team
,
competition
, and
season
for each match:
{
"team"
:
{
"id"
:
"874"
,
"name"
:
"Corinthians"
}
,
"competition"
:
{
"id"
:
"serie-a-brazil"
,
"name"
:
"Serie A Brazil"
}
,
"season"
:
{
"id"
:
"serie-a-brazil-2025"
,
"year"
:
"2025"
}
}
search_player
Search for a football player by name. Returns Transfermarkt and ESPN IDs for use with
get_player_profile
and
get_season_transfers
.
query
(str, required): Player name to search (e.g., "Salah", "Hugo Souza", "Mbappe")
Returns
data.results[]
with matched players, each containing
tm_player_id
,
espn_id
,
name
,
team
, and
competition
.
get_team_profile
Get basic team info (name, crest, venue).
Does not return squad/roster
— use
get_season_leaders
to find PL player IDs, then
get_player_profile
for individual player data.
team_id
(str, required): ESPN team ID
league_slug
(str, optional): League hint (faster resolution)
Returns
data.team
and
data.venue
.
data.players[]
is empty — see "Deep dive on a PL team" example below for the recommended workflow.
get_daily_schedule
Get all matches for a specific date across all leagues.
date
(str, optional): Date in YYYY-MM-DD format. Defaults to today.
Returns
data.date
and
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
}
}
Status values:
"not_started"
,
"live"
,
"halftime"
,
"closed"
,
"postponed"
.
get_event_summary
Get match summary with scores. Works for all leagues.
event_id
(str, required): Match/event ID
Returns
data.event
(same shape as daily schedule events).
get_event_lineups
Get match lineups. Works for all leagues (when available from ESPN).
event_id
(str, required): Match/event ID
Returns
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
Get match team statistics. Works for all leagues.
event_id
(str, required): Match/event ID
Returns
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
Get match timeline/key events (goals, cards, substitutions). Works for all leagues.
event_id
(str, required): Match/event ID
Returns
data.timeline[]
with goal, card, and substitution events.
get_team_schedule
Get schedule for a specific team — includes both past results and upcoming fixtures. Works for all leagues.
team_id
(str, required): ESPN team ID
league_slug
(str, optional): League hint (faster resolution)
season_year
(str, optional): Season year filter
competition_id
(str, optional): Filter results to a single competition (e.g., "serie-a-brazil", "premier-league")
get_head_to_head
UNAVAILABLE
— requires licensed data. Do not call this command; it will return empty results. Instead, use
get_team_schedule
for both teams and filter overlapping matches manually.
team_id
(str, required): First team ID
team_id_2
(str, required): Second team ID
get_event_xg
Get expected goals (xG) data from Understat.
Top 5 leagues only
EPL, La Liga, Bundesliga, Serie A, Ligue 1. Returns empty for other leagues.
event_id
(str, required): Match/event ID
Returns
data.teams[]
and
data.shots[]
:
{
"team"
:
{
"id"
:
"244"
,
"name"
:
"Brentford"
}
,
"qualifier"
:
"home"
,
"xg"
:
1.812
}
data.shots[]
contains individual shot data with xG per shot. Note: very recent matches (last 24-48h) may not be indexed on Understat yet.
get_event_players_statistics
Get player-level match statistics with xG enrichment. Works for all leagues (basic stats from ESPN). xG/xA enrichment only for top 5 leagues (Understat).
event_id
(str, required): Match/event ID
Returns
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
and
xa
fields only present for top 5 leagues.
get_missing_players
Get injured/missing/doubtful players.
Premier League only
(via FPL). Returns empty for other leagues.
season_id
(str, required): Season slug (must be
premier-league-*
)
Returns
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
}
Status values:
"injured"
,
"unavailable"
,
"doubtful"
,
"suspended"
.
get_season_transfers
Get transfer history for specific players via Transfermarkt. Works for any league.
season_id
(str, required): Season slug (used to filter transfers by year)
tm_player_ids
(list, required): Transfermarkt player IDs
Returns
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
Get player season stats via ESPN overview endpoint. Works for any league with ESPN athlete IDs.
player_id
(str, required): ESPN athlete ID
league_slug
(str, optional): League slug hint (e.g., "eng.1", "esp.1"). Defaults to auto-detect.
Returns season stats (goals, assists, appearances, etc.) and game log when available.
get_player_profile
Get player profile. Works for any player if you have their Transfermarkt or FPL ID. At least one ID required.
fpl_id
(str, optional): FPL player ID (PL players only)
tm_player_id
(str, optional): Transfermarkt player ID (any league)
With
tm_player_id
, returns
data.player
with:
{
"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"
:
"-"
}
]
}
With
fpl_id
, also includes
data.player.fpl_data
with FPL stats (points, form, ICT index, ownership, etc.).
Supported Leagues
Premier League, La Liga, Bundesliga, Serie A, Ligue 1, MLS, Championship, Eredivisie, Primeira Liga, Serie A Brazil, Champions League, European Championship, World Cup.
Data Sources
Source
What it provides
League coverage
ESPN
Scores, standings, schedules, lineups, match stats, timelines
All 13 leagues
openfootball
Schedules, standings, team lists (fallback when ESPN is down)
10 leagues (all except CL, Euros, World Cup)
Understat
xG per match, xG per shot, player xG/xA
Top 5 (EPL, La Liga, Bundesliga, Serie A, Ligue 1)
FPL
Top scorers, injuries, player stats, ownership
Premier League only
Transfermarkt
Market values, transfer history
Any player (requires tm_player_id)
For licensed data with full coverage across all sports (Sportradar, Opta, Genius Sports), see
Machina Sports
.
Examples
User: "Show me the Premier League table"
Call
get_current_season(competition_id="premier-league")
to get the current season_id
Call
get_season_standings(season_id=)
Present standings table with position, team, played, won, drawn, lost, GD, points
User: "How did Arsenal vs Liverpool go?"
Call
get_daily_schedule()
or
get_team_schedule(team_id="359")
to find the event_id
Call
get_event_summary(event_id="...")
for the score
Call
get_event_statistics(event_id="...")
for possession, shots, etc.
Call
get_event_xg(event_id="...")
for xG comparison (EPL — top 5 only)
Present match report with scores, key stats, and xG
User: "Deep dive on Chelsea's recent form"
Call
search_team(query="Chelsea")
→ team_id=363, competition=premier-league
Call
get_team_schedule(team_id="363", competition_id="premier-league")
→ find recent closed events
For each recent match, call in parallel:
get_event_xg(event_id="...")
for xG comparison and shot map
get_event_statistics(event_id="...")
for possession, shots, passes
get_event_players_statistics(event_id="...")
for individual player xG/xA
Call
get_missing_players(season_id=)
→ filter Chelsea's injured/doubtful players
Call
get_season_leaders(season_id=)
→ filter Chelsea players, get their FPL IDs
Call
get_player_profile(fpl_id="...", tm_player_id="...")
for key players — combine FPL stats (form, ownership, ICT) with Transfermarkt data (market value, transfer history)
Present: xG trend across matches, key player stats, injury report, market values
User: "What's Saka's market value?"
Call
get_player_profile(tm_player_id="433177")
for Transfermarkt data
Optionally add
fpl_id
for FPL stats if Premier League player
Present market value, value history, and transfer history
User: "Tell me about Corinthians"
Call
search_team(query="Corinthians")
→ team_id=874, competition=serie-a-brazil
Call
get_team_schedule(team_id="874", competition_id="serie-a-brazil")
for fixtures
Pick a recent match and call
get_event_timeline(event_id="...")
for goals, cards, subs
Note: xG, FPL stats, and season leaders are NOT available for Brazilian Serie A
Error Handling
When a command fails (wrong event_id, missing data, network error, etc.),
do not surface the raw error to the user
. Instead:
Catch it silently
— treat the failure as an exploratory miss, not a fatal error.
Try alternatives
— e.g., if an event_id returns no data, call
get_daily_schedule()
or
get_team_schedule()
to discover the correct ID. If ESPN is down, openfootball data may still be available via
get_season_standings
or
get_season_schedule
.
Only report failure after exhausting alternatives
— and when you do, give a clean human-readable message (e.g., "I couldn't find that match — can you confirm the teams or date?"), not a traceback or raw CLI output.
This is especially important when the agent is responding through messaging platforms (Telegram, Slack, etc.) where raw exec failures look broken.
Common Mistakes
These are the ONLY valid commands.
Do not invent or guess command names:
get_current_season
get_competitions
get_competition_seasons
get_season_schedule
get_season_standings
get_season_leaders
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
get_event_xg
get_event_players_statistics
get_missing_players
get_season_transfers
get_player_profile
get_player_season_stats
Commands that DO NOT exist
(commonly hallucinated):
get_standings
— the correct command is
get_season_standings
(requires
season_id
).
get_live_scores
— not available. Use
get_daily_schedule()
for today's matches; status field shows "live" for in-progress games.
get_team_squad
/
get_team_roster
—
get_team_profile
does NOT return players. Use
get_season_leaders
for PL player IDs, then
get_player_profile
for individual data.
get_transfers
— the correct command is
get_season_transfers
(requires
season_id
+
tm_player_ids
).
get_match_results
/
get_match
— use
get_event_summary
with an
event_id
.
get_player_stats
— use
get_event_players_statistics
for match-level stats, or
get_player_profile
for career data.
get_scores
/
get_results
— does not exist. Use
get_event_summary
with an
event_id
.
get_fixtures
— does not exist. Use
get_daily_schedule
for today's matches or
get_season_schedule
for a full season.
get_league_table
— does not exist. Use
get_season_standings
with a
season_id
.
Other common mistakes:
Using
get_season_leaders
or
get_missing_players
on non-PL leagues — they return empty. Check the Data Coverage table.
Using
get_event_xg
on leagues outside the top 5 — returns empty. Only works for EPL, La Liga, Bundesliga, Serie A, Ligue 1.
Guessing
team_id
or
event_id
instead of discovering them via
search_team
,
get_daily_schedule
, or
get_season_schedule
.
If you're unsure whether a command exists, check this list. Do not try commands that aren't listed above.
Troubleshooting
sports-skills
command not found
Package not installed. Run
pip install sports-skills
. If the package is not found on PyPI, install from GitHub:
pip install git+https://github.com/machina-sports/sports-skills.git
. Requires Python 3.10+ — see Setup section.
ModuleNotFoundError: No module named 'sports_skills'
Same as above — install the package. Prefer the CLI over Python imports to avoid path issues.
Empty results for PL-only commands on other leagues
:
get_season_leaders
and
get_missing_players
only return data for Premier League. They silently return empty for other leagues — check the Data Coverage table.
get_team_profile
returns empty players
This is expected — squad rosters are not available. To get player data for a PL team, use
get_season_leaders
to find players and their FPL IDs, then
get_player_profile(fpl_id="...")
for detailed stats. For Transfermarkt data, you need the player's
tm_player_id
.
Finding FPL IDs and Transfermarkt IDs
Use
get_season_leaders(season_id="premier-league-2025")
to discover FPL IDs for PL players. Transfermarkt IDs must be looked up on
transfermarkt.com
— the ID is the number at the end of the player's URL. Well-known examples: Cole Palmer =
568177
, Bukayo Saka =
433177
, Mbappe =
342229
.
No xG for recent matches
Understat data may lag 24-48 hours after a match ends. If
get_event_xg
returns empty for a recent top-5 match, try again later.
Wrong season_id format
Must be
{league-slug}-{year}
e.g.
"premier-league-2025"
. Not
"2025-2026"
, not
"EPL-2025"
. Use
get_current_season()
to discover the correct format.
Team/event IDs unknown
Use search_team(query="team name") to find team IDs by name, or get_season_teams to list all teams in a season. Use get_daily_schedule or get_season_schedule to find event IDs. IDs are ESPN numeric strings.
← 返回排行榜