Skip to main content

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)

Source distribution for datafc 2.11.0
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)

Table of built distributions (wheels) for datafc 2.11.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page