Football Data
Wire football scores, standings, xG, and FPL injury data into fantasy, betting-adjacent analytics, or sports dashboards using consistent ID conventions across ESPN, Understat, and FPL.
Overview
football-data is an agent skill for the Build phase that maps football API commands, ID conventions, and league coverage across ESPN, Understat, FPL, and Transfermarkt.
Install
npx skills add https://github.com/machina-sports/sports-skills --skill football-dataWhat is this skill?
- 13 leagues via ESPN: standings, schedules, lineups, timelines, team profiles
- Top-5 league xG via Understat on events and player stats
- Premier League-only FPL leaders, missing players, ownership, and ICT index
- Stable ID conventions: season_id, competition_id, ESPN team/event IDs, Transfermarkt tm_player_id
- Coverage matrix clarifies all-leagues vs top-5 vs PL-only commands
- 13 leagues via ESPN coverage
- Top 5 leagues for Understat xG
- PL-only FPL commands called out in matrix
Adoption & trust: 1.1k installs on skills.sh; 134 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are building a football app but agents confuse league coverage and mix ESPN, xG, and FPL identifiers across commands.
Who is it for?
Solo builders adding match data, standings, or FPL-aware features to a sports SaaS or CLI agent tool.
Skip if: Non-football products, pure UI clone work with no live data, or teams needing official league licensing documentation instead of integration IDs.
When should I use this skill?
Building or extending agent tools that fetch football standings, schedules, match events, xG, or FPL player status with correct source per league.
What do I get? / Deliverables
Integrations use the correct source per league with consistent IDs so schedules, xG, and FPL injury calls succeed on the first agent pass.
- Correct command selection per league
- Normalized ID mapping table in code
- Data coverage notes for product README
Recommended Skills
Journey fit
Football-data sits in Build because it is an integration reference for pulling structured match and player data into a product under development. Integrations subphase is correct for third-party sports APIs and source-specific command coverage, not for UI polish or launch SEO.
How it compares
Use as a sports-specific data integration skill, not as a generic REST client generator or frontend component library.
Common Questions / FAQ
Who is football-data for?
Developers and indie builders wiring football statistics and fantasy signals into agents, APIs, or dashboards across European leagues.
When should I use football-data?
During Build integrations when implementing schedules and standings; during Grow analytics when enriching lifecycle emails with match context; during Validate prototypes when demoing real fixtures on a landing MVP.
Is football-data safe to install?
It is documentation for external sports APIs—credentials and rate limits are yours to manage. Review the Security Audits panel on this Prism page before adding the skill to production agent workflows.
SKILL.md
READMESKILL.md - Football Data
# Football Data — API Reference ## ID Conventions - **season_id**: `{league-slug}-{year}` e.g. `"premier-league-2025"`, `"la-liga-2025"` (year = start year of the season) - **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) ## Data Coverage by 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. ## 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) | 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) | ## Commands (Detailed) ### 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`: ```json {"competition": {"id": "premier-league"}, "season": {"id": "premier-league-2025", "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. - `competition_id` (str, required): Competition slug ### get_season_schedule Get full season match schedule. - `season_id` (str, required): Season slug Returns `data.schedules[]`. ### get_season_standings Get league table for a season. - `season_id` (str, required): Season slug Returns `data.standings[].entries[]`: ```json { "position": 1, "team": {"id": "359", "name": "Arsenal", "abbreviation": "ARS"}, "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[]` with nested `player.name`, `team.name`, goals, assists, played_matches. ### get_season_teams Get teams in a season. - `season_id` (str, required): Season slug ### search_team Search for a team by name across all leagues. Uses fuzzy matching. - `query` (str, required): Team name - `competition_id` (str, optional): Limit to one league Returns `data.results[]` with `team`, `competition`, `season` for each match. ### search_player Search for a football player by name. - `query` (str, required): Player name Returns `data.results[]` with `tm_player_id`, `espn_id`, `name`, `team`, `competition`. ### get_team_profile Get basic t