FootyStats APIfootystats.org ↗
Access football league standings, team stats, live scores, player stats, and head-to-head match data from FootyStats via 8 structured endpoints.
What is the FootyStats API?
The FootyStats API exposes 8 endpoints covering football league standings, team performance metrics, live scores, player statistics, and head-to-head match data sourced from footystats.org. Use get_league_overview to pull full standings tables, or get_match_stats to retrieve possession, shots, xG, cards, and corners for a specific fixture. A search endpoint ties everything together by resolving team, league, or match names into paths for the detail endpoints.
curl -X GET 'https://api.parse.bot/scraper/da1a4a9a-3c0f-46fb-9c3b-79796e0bb203/search_teams_leagues?query=arsenal' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace footystats-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""FootyStats SDK walkthrough — bounded, re-runnable; every call capped."""
from parse_apis.footystats_api import FootyStats, TeamNotFound
client = FootyStats()
# Search for teams/leagues/matches by keyword
result = client.searchresults.search(query="arsenal", limit=3).first()
if result:
print(f"Found: {result.name} ({result.category}) at {result.path}")
# List all available leagues, take one and drill into its overview
league = client.leagues.list(limit=1).first()
if league:
overview = league.overview()
print(f"\n{overview.league_name} standings (top 3):")
for standing in overview.standings[:3]:
print(f" {standing.rank}. {standing.team} — {standing.pts} pts, {standing.ppg} ppg")
# Get player stats for that league
players = league.players()
print(f"\nTop scorer in {players.league_name}:")
if players.top_scorers:
top = players.top_scorers[0]
print(f" {top.name}: {top.value} goals")
# Fetch detailed team stats via the teams collection
try:
team = client.teams.get(path="/clubs/arsenal-fc-59")
print(f"\n{team.team_name} stats:")
wins = team.stats.get("wins")
if wins:
print(f" Win rate — overall: {wins.overall}, home: {wins.home}, away: {wins.away}")
except TeamNotFound as exc:
print(f"Team not found: {exc.path}")
# Live scores — always returns at least scheduled matches
for match in client.livematches.list(limit=3):
print(f" Match {match.match_id}: {match.team_a_score}-{match.team_b_score} ({match.minute})")
print("\nExercised: searchresults.search / leagues.list / league.overview / league.players / teams.get / livematches.list")
Full-text search across teams, leagues, and matches by keyword. Returns mixed results categorized as 'club', 'league', or 'match', each carrying a path usable with the corresponding detail endpoint (get_team_stats, get_league_overview, get_match_stats). Results are not paginated — one request returns all matches.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword (e.g. 'arsenal', 'premier league', 'barcelona'). |
{
"type": "object",
"fields": {
"items": "array of search result objects each with name (str), url (str), path (str), and category (str: 'club', 'league', or 'match')"
},
"sample": {
"data": {
"items": [
{
"url": "https://footystats.org/clubs/arsenal-fc-59",
"name": "Arsenal",
"path": "/clubs/arsenal-fc-59",
"category": "club"
}
]
},
"status": "success"
}
}About the FootyStats API
What the API Covers
The API provides structured football data across eight endpoints. get_leagues returns every league tracked on FootyStats — including name, country, slug, and a path field you pass directly into three other endpoints. get_league_overview uses that path to return the full standings table: rank, team, matches played, wins, draws, losses, goals for/against, goal difference, points, and points-per-game. get_league_player_stats returns top scorers, top assist leaders, and clean-sheet leaders for any league. get_league_detailed_stats narrows to a rolling 6-match form table with the same W/D/L/GF/GA/GD/PTS/PPG structure.
Team and Match Detail
get_team_stats takes a /clubs/ path (obtainable from search_teams_leagues) and returns per-stat breakdowns split across overall, home, and away — covering win/draw/loss percentages, goals, possession, shots, and fouls, plus season totals. get_match_stats takes a path ending in -h2h-stats and returns the match score, both team names, and a stats dict mapping stat labels (possession, xG, corners, cards, fouls) to per-team values. Stat keys vary by fixture.
Search and Live Scores
search_teams_leagues accepts a free-text query and returns mixed results typed as club, league, or match, each with a path ready to feed into the appropriate detail endpoint. Results are not paginated, so broad queries return everything in a single response. get_livescores requires no inputs and returns all currently active matches with team_a_score, team_b_score, and a minute field that handles numeric values, stoppage-time strings like '90+1', and status strings including 'HT', 'FT', 'Soon', and 'INTERRUPTED'.
Scope and Limitations
Stat keys in get_team_stats and get_match_stats are open-ended and vary by team, league, and season — callers should not assume a fixed schema. search_teams_leagues results are not paginated. Live score coverage depends on FootyStats indexing the match; the 'AWAITING_UPDATES' minute value indicates a match is tracked but data has not yet refreshed.
The FootyStats API is a managed, monitored endpoint for footystats.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when footystats.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official footystats.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a league table dashboard using
get_league_overviewstandings fields (rank, pts, ppg, gd). - Track top scorers and assist leaders per competition with
get_league_player_stats. - Display live match scores and in-progress minutes using
get_livescoreswith status-aware minute parsing. - Compare home vs. away form for any club by reading
homeandawaysplits fromget_team_stats. - Resolve a user-typed team or league name to a structured path via
search_teams_leaguesbefore calling detail endpoints. - Analyze recent team form by pulling the 6-match rolling table from
get_league_detailed_stats. - Build a head-to-head fixture preview using xG, possession, and shot data from
get_match_stats.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does FootyStats have an official developer API?+
What does `get_team_stats` return, and how does the home/away split work?+
stats dict where each key is a stat label (e.g. win percentage, shots per game, fouls) and each value is an object with overall, home, and away sub-keys. The exact stat keys present vary by team and season, so callers should iterate over whatever keys appear rather than expecting a fixed list.Does the API return historical match results or fixture schedules?+
get_livescores, head-to-head stats for specific fixtures via get_match_stats, and current-season standings and form tables. Historical result sequences and upcoming fixture schedules are not exposed. You can fork this API on Parse and revise it to add an endpoint targeting those data pages.Are `search_teams_leagues` results paginated?+
club, league, and match category entries, so filter by the category field in your application.Does the API expose player-level stats beyond top scorers and assists?+
get_league_player_stats endpoint covers top scorers, top assist leaders, and clean-sheet leaders at the league level. Individual player profiles, per-match player ratings, and passing or defensive metrics per player are not currently included. You can fork this API on Parse and revise it to target player profile pages and return that additional data.