football-data

Name: football-data
Author: machina-sports

1.9kinstalls27forks

How to install football-data?

machina-sports/sports-skills/football-data

$npx -y skills add machina-sports/sports-skills --skill football-data

Installs into the current project.

Summary

Football (soccer) data across the world's major leagues — standings, schedules, match stats, xG, transfers, player profiles, head-to-head history, team strength (Elo), and match forecasts. Zero config, no API keys. Covers Premier League, La Liga, Bundesliga, Serie A, Ligue 1, MLS

Files · 1

View on GitHub

SKILL.md

1	# Football Data
2
3	Before writing queries, consult `references/api-reference.md` for endpoints, ID conventions, and data shapes.
4
5	## Setup
6
7	Before first use, check if the CLI is available:
8	```bash
9	which sports-skills \|\| pip install sports-skills
10	```
11	If `pip install` fails (package not found or Python version error), install from GitHub:
12	```bash
13	pip install git+https://github.com/machina-sports/sports-skills.git
14	```
15	The package requires Python 3.10+. If your default Python is older, use a specific version:
16	```bash
17	python3 --version # check version
18	# If < 3.10, try: python3.12 -m pip install sports-skills
19	# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills
20	```
21	No API keys required.
22
23	## Quick Start
24
25	Prefer the CLI — it avoids Python import path issues:
26	```bash
27	sports-skills football get_daily_schedule
28	sports-skills football get_season_standings --season_id=premier-league-2025
29	```
30
31	Python SDK (alternative):
32	```python
33	from sports_skills import football
34
35	standings = football.get_season_standings(season_id="premier-league-2025")
36	schedule = football.get_daily_schedule()
37	```
38
39	## CRITICAL: Before Any Query
40
41	CRITICAL: Before calling any data endpoint, verify:
42	- Season ID is derived from `get_current_season(competition_id="...")` — never hardcoded.
43	- Team ID is resolved via `search_team(query="...")` and passed as the numeric `team_id`. For `get_head_to_head`, `get_team_strength`, and `get_match_forecast`, always pass IDs — ambiguous names (e.g. two "Paris" clubs) can resolve to the wrong team.
44	- The endpoint actually covers the league in question — see the Coverage & Source Map below. Coverage is uneven across sources; an uncovered call returns an empty payload with a `message`, not data.
45	- `get_event_xg` and `get_event_players_statistics` (with xG) are only called for top-5 leagues (EPL, La Liga, Bundesliga, Serie A, Ligue 1).
46	- `get_season_leaders` and `get_missing_players` are only called for Premier League seasons (season_id must start with `premier-league-`).
47
48	## Choosing the Season
49
50	Derive the current year from the system prompt's date (e.g., `currentDate: 2026-02-16` → current year is 2026).
51
52	- If the user specifies a season, use it as-is.
53	- 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.
54	- 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.
55	- MLS exception: MLS runs spring-fall within a single calendar year. Use `get_current_season(competition_id="mls")`.
56
57	## Coverage & Source Map
58
59	This skill stitches several free sources together. Coverage is not uniform — each endpoint works only where its underlying source has data. Check this before promising an answer; when an endpoint isn't covered, it returns an empty payload with an explanatory `message` (never an error) — read that message and fall back.
60
61	\| Endpoint(s) \| Source \| Coverage \|
62	\|---\|---\|---\|
63	\| standings, schedules, teams, event summary/lineups/stats/timeline \| ESPN \| All leagues (broadest — the backbone) \|
64	\| `get_event_xg`, `get_event_players_statistics` (xG fields) \| Understat \| Top 5 only (EPL, La Liga, Bundesliga, Serie A, Ligue 1). Not RFPL — Understat dropped it. \|
65	\| `get_season_leaders`, `get_missing_players` \| FPL \| Premier League only \|
66	\| `get_player_profile`, `get_season_transfe

People who liked this also viewed

6 picks

Type

football-data

1.9kinstalls27forks

View on GitHub

How to install football-data?

machina-sports/sports-skills/football-data

$npx -y skills add machina-sports/sports-skills --skill football-data

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Football Data
2
3	Before writing queries, consult `references/api-reference.md` for endpoints, ID conventions, and data shapes.
4
5	## Setup
6
7	Before first use, check if the CLI is available:
8	```bash
9	which sports-skills \|\| pip install sports-skills
10	```
11	If `pip install` fails (package not found or Python version error), install from GitHub:
12	```bash
13	pip install git+https://github.com/machina-sports/sports-skills.git
14	```
15	The package requires Python 3.10+. If your default Python is older, use a specific version:
16	```bash
17	python3 --version # check version
18	# If < 3.10, try: python3.12 -m pip install sports-skills
19	# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills
20	```
21	No API keys required.
22
23	## Quick Start
24
25	Prefer the CLI — it avoids Python import path issues:
26	```bash
27	sports-skills football get_daily_schedule
28	sports-skills football get_season_standings --season_id=premier-league-2025
29	```
30
31	Python SDK (alternative):
32	```python
33	from sports_skills import football
34
35	standings = football.get_season_standings(season_id="premier-league-2025")
36	schedule = football.get_daily_schedule()
37	```
38
39	## CRITICAL: Before Any Query
40
41	CRITICAL: Before calling any data endpoint, verify:
42	- Season ID is derived from `get_current_season(competition_id="...")` — never hardcoded.
43	- Team ID is resolved via `search_team(query="...")` and passed as the numeric `team_id`. For `get_head_to_head`, `get_team_strength`, and `get_match_forecast`, always pass IDs — ambiguous names (e.g. two "Paris" clubs) can resolve to the wrong team.
44	- The endpoint actually covers the league in question — see the Coverage & Source Map below. Coverage is uneven across sources; an uncovered call returns an empty payload with a `message`, not data.
45	- `get_event_xg` and `get_event_players_statistics` (with xG) are only called for top-5 leagues (EPL, La Liga, Bundesliga, Serie A, Ligue 1).
46	- `get_season_leaders` and `get_missing_players` are only called for Premier League seasons (season_id must start with `premier-league-`).
47
48	## Choosing the Season
49
50	Derive the current year from the system prompt's date (e.g., `currentDate: 2026-02-16` → current year is 2026).
51
52	- If the user specifies a season, use it as-is.
53	- 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.
54	- 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.
55	- MLS exception: MLS runs spring-fall within a single calendar year. Use `get_current_season(competition_id="mls")`.
56
57	## Coverage & Source Map
58
59	This skill stitches several free sources together. Coverage is not uniform — each endpoint works only where its underlying source has data. Check this before promising an answer; when an endpoint isn't covered, it returns an empty payload with an explanatory `message` (never an error) — read that message and fall back.
60
61	\| Endpoint(s) \| Source \| Coverage \|
62	\|---\|---\|---\|
63	\| standings, schedules, teams, event summary/lineups/stats/timeline \| ESPN \| All leagues (broadest — the backbone) \|
64	\| `get_event_xg`, `get_event_players_statistics` (xG fields) \| Understat \| Top 5 only (EPL, La Liga, Bundesliga, Serie A, Ligue 1). Not RFPL — Understat dropped it. \|
65	\| `get_season_leaders`, `get_missing_players` \| FPL \| Premier League only \|
66	\| `get_player_profile`, `get_season_transfe

People who liked this also viewed

6 picks

Type