A comprehensive Python library for accessing and analyzing data for the Top 5 European Leagues, including match statistics, player leaders, and transfer information. The library provides methods to rapidly expose them as an API as well as Create Training Data for ML related Analysis.
Sample ML project using the library: Premier League Predictions
pip install premier_league
pip install premier_league[pdf]
pip install premier_league[api]
pip install premier_league[lambda]
pip install premier_league[all]
Anyone is Welcome to Contribute and Fix an Exisiting Issue or a new Problem
pip install -e .
pip install -r requirements-test.txt # Only Required to run tests
# Install pre-commit for style checks (Optional)
pip install pre-commit
pre-commit install
MatchStatistics is a class for retrieving and analyzing detailed match-level statistics in the form of ML datasets from Premier League games and other top European leagues. It provides access to extensive game data including team performance metrics, player statistics, and match events for ML Training or Analysis
The data is stored in a SQLite database that is automatically initialized in the user's local directory upon first use. The database schema includes:
The database is automatically initialized on first use
from premier_league import MatchStatistics
# Initialize with default database
stats = MatchStatistics()
# The database is automatically initialized on first use
# Default location: data/premier_league.db
You can override the default location. (WARNING: If a Database is already created then you invoke the class with the wrong file location, a new SQL dump is going to be triggered with a new sqlite database)
stats = MatchStatistics(db_filename="custom_db_name.db", db_directory="custom_directory/my_file")
from premier_league import MatchStatistics
# Initialize match statistics
stats = MatchStatistics()
# Get specific team's match history
arsenal_games = stats.get_team_games("Arsenal")
# Get games for a specific season and match week
season_games = stats.get_games_by_season("2023-2024", match_week=5)
# Get recent games before a specific date
from datetime import datetime
recent_games = stats.get_games_before_date(
date=datetime(2024, 2, 1),
limit=10,
team="Manchester City"
)
get_team_games(team_name: str) -> List[dict]Retrieves complete match history for a specific team.
stats = MatchStatistics()
arsenal_games = stats.get_team_games("Arsenal")
get_games_by_season(season: str, match_week: int) -> List[dict]Retrieves all games for a specific season and match week.
games = stats.get_games_by_season("2023-2024", match_week=15)
get_games_before_date(date: datetime, limit: int = 10, team: Optional[str] = None) -> List[dict]Retrieves games before a specific date with optional team filter.
recent_games = stats.get_games_before_date(
date=datetime(2024, 2, 1),
limit=5
)
get_game_stats_before_date(date: datetime, limit: int = 10, team: Optional[str] = None) -> List[dict]Retrieves detailed game statistics before a specific date.
recent_stats = stats.get_game_stats_before_date(
date=datetime(2024, 2, 1),
team="Liverpool"
)
get_future_match(self, league: str, team=None) -> DictRetrieves the next match for a specific team or league.
next_match = stats.get_future_match(league="Premier League", team="Arsenal")
update_data_set()Updates the database with the latest available match data.
stats = MatchStatistics()
stats.update_data_set()
create_dataset(output_path: str, rows_count: int = None, lag: int = 10, weights: Literal["lin", "exp"] = None, params: float = None)This method exports match statistics to a CSV file formatted for Machine Learning applications.
output_path (str): The file path where the dataset will be saved.rows_count (int, optional): Number of data rows to export. If not specified, all available data is exported.lag (int, default = 10): The number of previous games to aggregate for each game. For example, with lag=10, the dataset will include the average statistics of the last 10 games for each team in each row.weights (str, optional): Determines how the previous games are weighted:
'lin': Linear weighting, where recent games have higher importance.'exp': Exponential weighting, where recent games have exponentially higher importance.params (float, optional): Required when using exponential weighting. Specifies the base constant for exponential weight calculations.MatchStatistics().create_dataset("premier_league_stats.csv", lag=2)
get_total_game_count()Retrieves the total number of games in the database.
total_games = MatchStatistics().get_total_game_count()
Each game statistics record includes detailed metrics broken down by position groups (FW, MF, DF):
{
"id":1,
"game_id":"GAME_00001",
"team_id":"TEAM_00001",
"xG":2.3,
"xA":1.8,
"xAG":1.5,
"shots_total_FW":8,
"shots_total_MF":5,
"shots_total_DF":1,
"shots_on_target_FW":4,
"shots_on_target_MF":2,
"shots_on_target_DF":0,
"shot_creating_chances_FW":6,
"shot_creating_chances_MF":8,
"shot_creating_chances_DF":2,
"goal_creating_actions_FW":2,
"goal_creating_actions_MF":3,
"goal_creating_actions_DF":1,
"passes_completed_FW":125,
"passes_completed_MF":245,
"passes_completed_DF":180,
"pass_completion_percentage_FW":78.5,
"pass_completion_percentage_MF":89.2,
"pass_completion_percentage_DF":92.5,
"key_passes":12,
"passes_into_final_third":45,
"passes_into_penalty_area":18,
"crosses_into_penalty_area":15,
"progressive_passes":35,
"tackles_won_FW":3,
"tackles_won_MF":8,
"tackles_won_DF":12,
"dribblers_challenged_won_FW":2,
"dribblers_challenged_won_MF":6,
"dribblers_challenged_won_DF":8,
"blocks_FW":1,
"blocks_MF":4,
"blocks_DF":9,
"interceptions_FW":2,
"interceptions_MF":8,
"interceptions_DF":12,
"clearances_FW":0,
"clearances_MF":3,
"clearances_DF":15,
"errors_leading_to_goal":0,
"possession_rate":58,
"touches_FW":145,
"touches_MF":280,
"touches_DF":225,
"touches_att_pen_area_FW":12,
"touches_att_pen_area_MF":5,
"touches_att_pen_area_DF":1,
"take_ons_FW":8,
"take_ons_MF":10,
"take_ons_DF":2,
"successful_take_ons_FW":3,
"successful_take_ons_MF":6,
"successful_take_ons_DF":1,
"carries_FW":45,
"carries_MF":85,
"carries_DF":35,
"carries_into_penalty_area":8,
"total_carrying_distance_FW":450,
"total_carrying_distance_MF":850,
"total_carrying_distance_DF":250,
"dispossessed_FW":4,
"dispossessed_MF":5,
"dispossessed_DF":1,
"aerials_won_FW":6,
"aerials_won_MF":8,
"aerials_won_DF":12,
"aerials_lost_FW":4,
"aerials_lost_MF":5,
"aerials_lost_DF":3,
"miss_controlled_FW":3,
"miss_controlled_MF":2,
"miss_controlled_DF":1,
"save_percentage":75.0,
"saves":4,
"PSxG":1.2,
"passes_completed_GK":22,
"crosses_stopped":3,
"passes_40_yard_completed_GK":8,
"yellow_card":2,
"red_card":0,
"pens_won":0,
"pens_conceded":0,
"fouls_committed_FW":2,
"fouls_committed_MF":5,
"fouls_committed_DF":3,
"fouls_drawn_FW":4,
"fouls_drawn_MF":3,
"fouls_drawn_DF":1,
"offside_FW":3,
"offside_MF":1,
"offside_DF":0
}
The database is automatically initialized using init_db() which:
def init_db(
db_filename: str,
db_directory: str
) -> Session:
"""
Initialize the database and seed initial data
"""
# Creates user data directory
data_dir = appdirs.user_data_dir(db_directory)
# Sets up database if not exists
db_path = os.path.join(data_dir, db_filename)
if not os.path.exists(db_path):
# Initialize from SQL dump
conn = sqlite3.connect(db_path)
sql_path = files("premier_league").joinpath("data/premier_league.sql")
conn.executescript(sql_file.read())
# Create SQLAlchemy session
engine = create_engine(f"sqlite:///{db_path}")
SessionLocal = sessionmaker(bind=engine)
session = SessionLocal()
# Seed initial league data
seed_initial_data(session)
return session
The database is seeded with these leagues by default:
RankingTable Fetches Team ranking data for a given season and league.
find_season_limit can be invoked to find the oldest supported seasons in RankingTable class
from premier_league import RankingTable
# Initialize the ranking table for the current season
ranking = RankingTable()
# Or specify a target season (None Defaults to Current Season)
ranking = RankingTable(target_season="1995-1996")
# Or specify a different league (None Defaults to Premier League)
ranking = RankingTable(league="Serie A")
get_ranking_list() -> listRetrieves the current Premier League ranking data in list format.
from premier_league import RankingTable
ranking = RankingTable().get_ranking_list()
get_ranking_csv(file_name: str, header: str = None) -> NoneExports the ranking data to a CSV file.
file_name (str): Name of the output file (without extension)header (str, optional): Header to include in the CSV filefrom premier_league import RankingTable
ranking = RankingTable()
ranking.get_ranking_csv("premier_league_rankings", "Season 2023-24")
get_prem_ranking_json(file_name: str, header: str = None) -> NoneExports the ranking data to a JSON file.
file_name (str): Name of the output file (without extension)header (str, optional): Header to use as the parent key in the JSON structurefrom premier_league import RankingTable
ranking = RankingTable(league="Serie A")
ranking.get_ranking_json("premier_league_rankings", "PL_Rankings")
get_prem_ranking_pdf(file_name: str) -> NoneGenerates a formatted PDF file containing the Premier League ranking table.
file_name (str): Name of the output file (without extension)from premier_league import RankingTable
ranking = RankingTable()
ranking.get_ranking_pdf("premier_league_standings")
The ranking data is structured as a list of lists, where each inner list contains:
Example:
[
["Position", "Team", "MP", "W", "D", "L", "GF", "GA", "GD", "Points"],
["1", "Manchester City", "38", "32", "4", "2", "102", "31", "71", "100"],
# ... more entries
]
PlayerSeasonLeaders is a specialized scraper for retrieving and processing player statistics, focusing on either goals or assists for a specific season.
find_season_limit can be invoked to find the oldest supported seasons in SeasonPlayerLeaders class
from premier_league import PlayerSeasonLeaders
# Initialize for current season's top scorers
scorers = PlayerSeasonLeaders(stat_type='G')
# Initialize for current season's top assisters
assists = PlayerSeasonLeaders(stat_type='A')
# For a specific season's data
scorers_2022 = PlayerSeasonLeaders(stat_type='G', target_season='2022-23')
# For a specific League
scorers_ligue_1 = PlayerSeasonLeaders(stat_type='A', league="ligue 1")
get_top_stats_list(limit: int = None) -> listReturns processed list of top players and their statistics.
limit: Optional number of players to return (defaults to 100)# Get top 10 scorers of Premier League
scorers = PlayerSeasonLeaders(stat_type='G')
top_10 = scorers.get_top_stats_list(limit=10)
get_top_stats_csv(file_name: str, header: str = None, limit: int = None)Exports statistics to CSV format.
scorers = PlayerSeasonLeaders(stat_type='G', league="Serie A")
scorers.get_top_stats_csv("top_scorers", header="2023-24 Season", limit=20)
get_top_stats_json(file_name: str, header: str = None, limit: int = None)Exports statistics to JSON format.
scorers = PlayerSeasonLeaders(stat_type='A')
scorers.get_top_stats_json("top_scorers", header="PL_Scorers", limit=20)
get_top_stats_pdf(file_name: str)Creates formatted PDF of top 20 players.
scorers = PlayerSeasonLeaders(stat_type='A')
scorers.get_top_stats_pdf("premier_league_top_scorers")
List of lists with the following columns:
Example:
[
["Name", "Country", "Club", "Goals", "In Play Goals+Penalty"],
["Erling Haaland", "Norway", "Manchester City", "36", "30+6"],
# ... more entries
]
List of lists with the following columns:
Example:
[
["Name", "Country", "Club", "Assists"],
["Kevin De Bruyne", "Belgium", "Manchester City", "16"],
# ... more entries
]
Transfers is a specialized scraper for retrieving and processing transfer data for teams in a specific season. It provides methods to fetch, display, and export both incoming and outgoing transfers.
find_season_limit can be invoked to find the oldest supported seasons in SeasonPlayerLeaders class
Disclaimer Some Seaons are not available due to World Events (e.g. WWII)
from premier_league import Transfers
# Initialize for current season
transfers = Transfers()
# Initialize for specific season and league
transfers_2022 = Transfers(target_season="2022-23", league="La Liga")
# Turn Off Caching and Fetch Fresh Data
transfers_no_cache = Transfers(cache=False)
# Print transfer table for a specific team
transfers.print_transfer_table("Arsenal")
# Get list of all teams in the specified season for referencing.
all_teams = transfers.get_all_current_teams()
transfer_in_table(team: str) -> list[list[str]]Get incoming transfers for a specific team.
arsenal_ins = transfers.transfer_in_table("Arsenal FC")
transfer_out_table(team: str) -> list[list[str]]Get outgoing transfers for a specific team.
arsenal_outs = transfers.transfer_out_table("Arsenal FC")
print_transfer_table(team: str) -> NoneDisplay formatted transfer tables (both in and out) for a team.
transfers.print_transfer_table("Manchester United")
get_all_current_teams() -> list[str]Get list of all teams in the current season.
teams = transfers.get_all_current_teams()
transfer_csv(team: str, file_name: str, transfer_type: Literal["in", "out", "both"] = "both")Export transfer data to CSV format.
# Export all transfers
transfers.transfer_csv("Chelsea", "chelsea_transfers")
# Export only incoming transfers
transfers.transfer_csv("Chelsea", "chelsea_incoming", transfer_type="in")
# Export only outgoing transfers
transfers.transfer_csv("Chelsea", "chelsea_outgoing", transfer_type="out")
transfer_json(team: str, file_name: str, transfer_type: Literal["in", "out", "both"] = "both")Export transfer data to JSON format.
# Export all transfers
transfers.transfer_json("Liverpool", "liverpool_transfers")
# Export specific transfer type (in, out)
transfers.transfer_json("Liverpool", "liverpool_ins", transfer_type="in")
Each transfer record contains the following columns:
Example Data Structure:
{
"arsenal in transfers": [
# Incoming transfers
[
["Date", "Name", "Position", "Club"],
["01/07", "Kai Havertz", "MF", "Chelsea FC"],
# ... more entries
]
],
"arsenal out transfers": [
[
["Date", "Name", "Position", "Club"],
["30/06", "Granit Xhaka", "MF", "Bayer Leverkusen"],
# ... more entries
]
],
# ... more teams
}
TeamNotFoundError if specified team isn't found in the seasonprint_transfer_table method uses PrettyTable for formatted console outputThis API provides access to Premier League player statistics, including goals and assists data. It supports both direct data retrieval and file exports in CSV and JSON formats.
GET /players/goals
Retrieve a list of top goalscorers in JSON format.
season (optional): Season identifier (e.g., "2023-2024")limit (optional): Maximum number of players to returnleague (optional): League specification (Defaults to Premier League){
"data": [
{
"name": "Erling Haaland",
"country": "Norway",
"club": "Manchester City",
"goals": "36",
"goals_breakdown": "30+6"
}
]
}
GET /players/assists
Retrieve a list of top assist providers in JSON format.
season (optional): Season identifier (e.g., "2023-2024")limit (optional): Maximum number of players to returnleague (optional): League specification (Defaults to Premier League){
"data": [
{
"name": "Kevin De Bruyne",
"country": "Belgium",
"club": "Manchester City",
"assists": "16"
}
]
}
GET /players/goals/csv_file
Download top goalscorers data as a CSV file.
season (optional): Season identifier (e.g., "2023-2024")filename (required): Name for the exported file (without extension)header (optional): Custom header for the CSV filelimit (optional): Maximum number of players to returnleague (optional): League name (defaults to "Premier League")GET /players/assists/csv_file
Download top assist providers data as a CSV file.
season (optional): Season identifier (e.g., "2023-2024")filename (required): Name for the exported file (without extension)header (optional): Custom header for the CSV filelimit (optional): Maximum number of players to returnleague (optional): League name (defaults to "Premier League")GET /players/goals/json_file
Download top goalscorers data as a JSON file.
season (optional): Season identifier (e.g., "2023-2024")filename (required): Name for the exported file (without extension)header (optional): Custom metadata for the JSON filelimit (optional): Maximum number of players to returnleague (optional): League name (defaults to "Premier League")GET /players/assists/json_file
Download top assist providers data as a JSON file.
season (optional): Season identifier (e.g., "2023-2024")filename (required): Name for the exported file (without extension)header (optional): Custom metadata for the JSON filelimit (optional): Maximum number of players to returnleague (optional): League name (defaults to "Premier League")| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| season | string | No | Premier League season identifier | "2023-2024" |
| limit | integer | No | Maximum number of results to return | 10 |
| filename | string | Yes* | Output filename for file exports | "top_scorers" |
| header | string | No | Custom header/metadata for exports | "PL Stats" |
| league | string | Yes* | Target League (defalts to PL) | "Bundesliga" |
* Required only for file export endpoints
The API returns standard HTTP status codes:
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request (invalid parameters) |
| 500 | Internal Server Error |
Common error responses:
{
"error": "Limit must be a number"
}
{
"error": "Missing filename parameter"
}
GET /players/goals?season=2023-2024&limit=5
GET /players/assists/csv_file?limit=10&filename=top_assists&header=Premier League Assists
GET /players/goals/json_file?filename=goalscorers&header=Goal Statistics
# Get top scorers
curl "http://api.example.com/players/goals?limit=5"
# Download assists CSV
curl -O "http://api.example.com/players/assists/csv_file?filename=assists&limit=10"
This API provides access to Premier League standings and team rankings. It supports both detailed and simplified table views, along with multiple export formats including CSV, JSON, and PDF.
GET /ranking
Retrieve detailed Premier League standings with comprehensive team statistics.
season (optional): Season identifier (e.g., "2023-2024")header (optional): Include additional metadata in responseleague (optional): League specification (Defaults to Premier League){
"data": {
"season": "2023-2024",
"standings": [
{
"position": 1,
"team": "Arsenal",
"played": 38,
"won": 25,
"drawn": 8,
"lost": 5,
"goals_for": 88,
"goals_against": 43,
"goal_difference": 45,
"points": 83
}
]
}
}
GET /ranking/table
Retrieve a simplified version of the league standings.
season (optional): Season identifier (e.g., "2023-2024")league (optional): League specification (Defaults to Premier League){
"data": [
["Pos", "Team", "P", "W", "D", "L", "GF", "GA", "GD", "Pts"],
[1, "Arsenal", 38, 25, 8, 5, 88, 43, 45, 83]
]
}
GET /ranking/csv_file
Download Premier League standings as a CSV file.
season (optional): Season identifier (e.g., "2023-2024")filename (required): Name for the exported file (without extension)league (optional): League specification (Defaults to Premier League)GET /ranking/json_file
Download Premier League standings as a JSON file.
season (optional): Season identifier (e.g., "2023-2024")filename (required): Name for the exported file (without extension)league (optional): League specification (Defaults to Premier League)GET /ranking/pdf_file
Download League standings as a formatted PDF file.
season (optional): Season identifier (e.g., "2023-2024")filename (required): Name for the exported file (without extension)league (optional): League specification (Defaults to Premier League)| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| season | string | No | Premier League season identifier | "2023-2024" |
| filename | string | Yes* | Output filename for file exports | "standings" |
| header | string | No | Custom metadata for response | "PL Rankings" |
* Required only for file export endpoints
The API returns standard HTTP status codes:
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 500 | Internal Server Error |
Common error response:
{
"error": "Missing filename parameter"
}
GET /ranking
GET /ranking/table?season=2023-2024
# CSV Export
GET /ranking/csv_file?filename=premier_league_standings&season=2023-2024
# JSON Export
GET /ranking/json_file?filename=pl_rankings&season=2023-2024
# PDF Export
GET /ranking/pdf_file?filename=standings_report&season=2023-2024
# Get full standings
curl "http://api.example.com/ranking"
# Download PDF report
curl -O "http://api.example.com/ranking/pdf_file?filename=standings"
# Get simplified table for specific season
curl "http://api.example.com/ranking/table?season=2023-2024"
position: Current league positionteam: Team nameplayed: Games playedwon: Games wondrawn: Games drawnlost: Games lostgoals_for: Goals scoredgoals_against: Goals concededgoal_difference: Goal difference (GF - GA)points: Total pointsThis API provides access to Premier League transfer data, allowing you to retrieve information about player transfers for specific teams. It supports both incoming and outgoing transfers and offers multiple export formats.
GET /all_teams
Retrieve a list of all teams in the Premier League for a given season.
season (optional): Season identifier (e.g., "2023-2024")league (optional): League specification (Defaults to Premier League){
"data": [
"Arsenal",
"Aston Villa",
"Brighton",
"Burnley",
...
]
}
GET /transfers/in
Retrieve all incoming transfers for a specific team.
season (optional): Season identifier (e.g., "2023-2024")team (required): Team nameleague (optional): League specification (Defaults to Premier League){
"data": [
{
"date": "01/07",
"name": "Kai Havertz",
"position": "MF",
"previous_club": "Chelsea"
}
]
}
GET /transfers/out
Retrieve all outgoing transfers for a specific team.
season (optional): Season identifier (e.g., "2023-2024")team (required): Team nameleague (optional): League specification (Defaults to Premier League){
"data": [
{
"date": "30/06",
"name": "Granit Xhaka",
"position": "MF",
"new_club": "Bayer Leverkusen"
}
]
}
GET /transfers/csv_file
Download transfer data as a CSV file.
season (optional): Season identifier (e.g., "2023-2024")team (required): Team namefilename (required): Name for the exported file (without extension)transfer_type (optional): Type of transfers to include:
"in": Only incoming transfers"out": Only outgoing transfers"both": Both incoming and outgoing transfers (default)league (optional): League name (defaults to "Premier League")GET /transfers/json_file
Download transfer data as a JSON file.
season (optional): Season identifier (e.g., "2023-2024")team (required): Team namefilename (required): Name for the exported file (without extension)transfer_type (optional): Type of transfers to include:
"in": Only incoming transfers"out": Only outgoing transfers"both": Both incoming and outgoing transfers (default)league (optional): League name (defaults to "Premier League")| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| season | string | No | Premier League season identifier | "2023-2024" |
| team | string | Yes* | Team name | "Arsenal" |
| filename | string | Yes** | Output filename for file exports | "transfers" |
| transfer_type | string | No | Type of transfers to include | "both" |
| league | string | Yes* | Target league (Defaults to PL) | "Serie A" |
* Required for all transfer-related endpoints except /all_teams
** Required only for file export endpoints
The API returns standard HTTP status codes:
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request (missing or invalid parameters) |
| 500 | Internal Server Error |
Common error responses:
{
"error": "Missing team parameter"
}
{
"error": "Missing filename parameter"
}
{
"error": "Invalid type parameter"
}
GET /all_teams
GET /transfers/in?team=Arsenal
GET /transfers/csv_file?team=Manchester%20United&filename=united_transfers&transfer_type=both
# Get all teams
curl "http://api.example.com/all_teams"
# Get incoming transfers
curl "http://api.example.com/transfers/in?team=Chelsea"
# Download transfer data
curl -O "http://api.example.com/transfers/json_file?team=Liverpool&filename=liverpool_transfers"
date: Transfer date (DD/MM format)name: Player nameposition: Player position (e.g., MF, FW, DF, GK)previous_club/new_club: Club involved in the transferAll Flask API Endpoints can be Deployed via AWS Lambda and Serverless Framework
A Preconfigured Serverless File is Rooted with the Lambda Code. All Files Created are saved in a specified S3 Bucket
- s3:PutObject
- s3:GetObject
npm install -g serverless
npm install -g serverless-python-requirements
S3_BUCKET_NAME=${s3 bucket name} python -m premier_league.lambda_functions.deploy_premier_league --aws-profile ${AWS IAM Account name} --region ${Your Region}
FAQs
Premier League Data Analysis Package
We found that premier-league demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.