datafc v2.11.0
Football data from Sofascore, ClubElo, eloratings.net (Elo since 1872) and tff.org (Turkish federation) as pandas DataFrames. 60 functions total, each with an async mirror under datafc.aio, optional DiskCache.
pip install datafc
Sofascore — from datafc import ...
Grouped by the argument each function needs. Chain them: id → root frame → derived frame.
Discovery
| Function | Purpose |
|---|---|
search_data(query, entity_type=None) |
search teams, players, tournaments, managers |
seasons_data(tournament_id) |
every season of a tournament |
season_rounds_data(tournament_id, season_id) |
defined matchweeks |
Root (id-driven)
| Function | Purpose |
|---|---|
standings_data(tournament_id, season_id) |
Total / Home / Away table |
match_data(tournament_id, season_id, week_number=None, tournament_type=None, tournament_stage=None) |
fixtures + scores |
past_matches_data(...) |
same signature; H2H history per pair |
team_match_history_data(team_id) |
full match history for one team |
league_player_stats_data(tournament_id, season_id, order='-rating', accumulation='total', fields=None, position=None, max_players=100) |
wide-format player leaderboard |
referee_stats_data(referee_id) |
per-tournament career stats |
tournament_type ∈ {"uefa", "world_cup", "league_playoff"} with matching tournament_stage (group_stage_week, round_of_16, quarterfinals, semifinals, final, …).
From standings_df
| Function | Purpose |
|---|---|
team_data(standings_df) |
profile, kits, manager, venue |
team_stats_data(standings_df, tournament_id, season_id, season=None) |
season team stats (long) |
team_transfers_data(standings_df) |
team transfer log |
player_stats_data(standings_df, tournament_id, season_id) |
top players per team |
squad_data(standings_df) |
full roster |
upcoming_matches_data(standings_df) |
upcoming fixtures |
From match_df
| Function | Purpose |
|---|---|
match_details_data |
referee + venue |
formations_data |
formation strings |
match_stats_data |
team stats per match |
match_odds_data |
1/X/2 odds |
match_h2h_data |
head-to-head record |
momentum_data |
minute-by-minute momentum |
pregame_form_data |
last-5 form, rating, position, market value |
shots_data |
every shot (xG, xGOT, body part, situation) |
lineups_data |
XI + subs + per-match player stats |
substitutions_data |
substitutions |
incidents_data |
goals, cards, VAR |
average_positions_data |
average pitch position (X/Y) |
goal_networks_data |
coordinates for every action in a goal sequence |
From lineups_df
| Function | Purpose |
|---|---|
coordinates_data(lineups_df) |
touch heatmap per player |
rating_breakdown_data(lineups_df) |
every pass / dribble / defensive action / ball-carry with start-end coordinates and outcome flags |
Or skip lineups_df and pass ids directly: coordinates_data(player_id=1091116, game_id=[16421105, 15534041]). Both accept an int or a list; every player/game combination is requested and combinations the player did not play are skipped.
From squad_df
| Function | Purpose |
|---|---|
player_data |
profile |
player_attribute_overviews_data |
radar attributes + baselines |
player_transfers_data |
transfer history |
player_career_stats_data |
season-by-season career stats |
player_national_team_data |
international career |
player_match_log_data |
match-by-match in-game stats (wide) |
Or skip squad_df and pass player_id (int or list) directly:
from datafc import player_data, player_transfers_data
player_data(player_id=1091116)
player_transfers_data(player_id=[1091116, ...])
Pass either squad_df or player_id, not both. Without a squad_df, player_name is only filled by player_data; other functions leave it empty. Exports are named from the ids, e.g. sofascore_player_data_player_1091116.json, or ..._player_1091116_and_more.json for a list (sofascore_coordinates_data_player_1091116_game_16421105_and_more.json for coordinates_data).
ClubElo — from datafc import clubelo
Club names use ClubElo spelling (Man City, Real Madrid, Paris SG).
| Function | Purpose |
|---|---|
daily_ranking_data(date) |
full ranking on a calendar day ("YYYY-MM-DD" or date) |
club_history_data(club) |
Elo history for one club (pre-1960 values are provisional) |
fixtures_data() |
probability grid for upcoming matches |
EloRatings — from datafc import eloratings
Country arguments are page slugs (Czech_Republic, United_States).
| Function | Purpose |
|---|---|
world_ranking_data() |
current national-team ranking |
country_matches_data(country) |
full international match history |
country_codes_data() |
code → country |
tournament_codes_data() |
code → tournament |
tournament_editions_data() |
edition list with dates + slugs |
tournament_groups_data() |
subcode → group code (e.g. WC qualifiers → WQT) |
teams_data() |
legacy country code → ISO |
TFF — from datafc import tff
Süper Lig, 1. Lig, 2. Lig, 3. Lig.
Discovery / league
| Function | Purpose |
|---|---|
fixtures_data(page_id, week=None, group=None, playoff=False, round=None, stage=None) |
weekly fixtures or play-off bracket (stage picks a stage group, e.g. Süper Lig 2011/12 Süper Final) |
standings_data(page_id, week, group=None, stage=None) |
league table (group required for 2. Lig / 3. Lig; stage picks a play-off table, e.g. Süper Lig 2011/12) |
team_data(club_id) |
club profile |
From match_id
| Function | Purpose |
|---|---|
match_details_data |
teams, score, officials |
match_lineups_data |
XI + bench |
match_staff_data |
head coaches |
match_goals_data |
goals with type (F/H/P/K/KG) |
match_cards_data |
bookings (yellow / red / second_yellow) |
From player_id
| Function | Purpose |
|---|---|
player_data |
profile (licence, current club) |
player_career_data |
licence history |
player_national_matches_data |
national-team appearances |
player_goals_data |
every recorded goal |
player_matches_data(player_id, season) |
club matches in a season ("2025-2026") |
player_cards_data(player_id, season) |
bookings in a season |
Async
Every function has a mirror in datafc.aio with the same signature:
import asyncio
from datafc import aio
async def main():
tasks = [aio.match_data(52, 63814, week_number=w) for w in range(1, 39)]
return await asyncio.gather(*tasks, return_exceptions=True)
asyncio.run(main())
Cache
from datafc import DiskCache
cache = DiskCache(cache_dir=".datafc_cache", ttl_hours=24)
Pass cache=cache to any function. ttl_hours=0 disables expiry; cache.clear() empties it.
Exceptions
DataFCError (base), InvalidParameterError, APIError, RateLimitError, ServerError, DataNotAvailableError.
Metadata
Release files for datafc 2.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| datafc-2.11.0.tar.gz | 81.1 kB | Without provenance | Details for datafc-2.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| datafc-2.11.0-py3-none-any.whl | Python 3 | none | any | Details for datafc-2.11.0-py3-none-any.whl |
Total release size: 211.1 kB
Release files / datafc-2.11.0.tar.gz
| Download URL | datafc-2.11.0.tar.gz |
|---|---|
| Size | 81.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9ec3619e53c969bd15328b7db6105b460fc566260cc32c4034bb7f5c5b88ed1f
|
|
BLAKE2b-256 checksum How to use checksums |
e86df4fdccca58c3e2cd1299b9bf33c134be21d867af932df53b38dbe8095d9c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.9
|
Release files / datafc-2.11.0-py3-none-any.whl
| Download URL | datafc-2.11.0-py3-none-any.whl |
|---|---|
| Size | 129.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
78865190de047d858b5cfc83bd33c5ffe6f4ee17646163bcdedeb32ab6620398
|
|
BLAKE2b-256 checksum How to use checksums |
35dfe8ad91170e9fc3f8e18fc9168f8ea2180e58593bad6d2e338337fa4c2078
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.9
|
Security for datafc 2.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.