Skip to content

kayoMichael/premier_league

BranchesTags

Repository files navigation

Premier League Data Library

Tests Python Versions PyPI version

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

Installation

pip install premier_league

PDF Export Methods (Optional)

pip install premier_league[pdf]

API Methods (Optional)

pip install premier_league[api]

Lambda Methods (Optional)

pip install premier_league[lambda]

All Methods

pip install premier_league[all]

Local Development

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

Features

📊 Match Statistics

📊 Ranking Table

📊 Player Leaders

📊 Transfers

📊 Flask API Docs

📊Lambda Docs

MatchStatistics

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

Data Structure

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:

Core Tables

  • League: Stores league information and update status Model
  • Team: Contains team details and league associations Model
  • Game: Records match details and scores Model
  • GameStats: Stores detailed match statistics Model

Database Initialization

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")

Usage

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"
)

Core Features

Team Statistics Retrieval

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)

Time-Based Queries

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) -> Dict

Retrieves the next match for a specific team or league.

next_match = stats.get_future_match(league="Premier League", team="Arsenal")

Data Management

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()

Data Format

Game Statistics Fields

Each game statistics record includes detailed metrics broken down by position groups (FW, MF, DF):

Attacking Metrics

  • Expected Goals (xG)
  • Expected Assisted Goals (xAG)
  • Shots (Total and On Target)
  • Shot Creating Actions
  • Goal Creating Actions

Passing Metrics

  • Passes Completed
  • Pass Completion Percentage
  • Key Passes
  • Progressive Passes
  • Passes into Final Third
  • Passes into Penalty Area

Defensive Metrics

  • Tackles Won
  • Blocks
  • Interceptions
  • Clearances
  • Errors Leading to Goal

Possession Metrics

  • Possession Rate
  • Touches
  • Take-ons (Attempted and Successful)
  • Carries
  • Carrying Distance
  • Ball Control Metrics

Miscellaneous

  • Fouls (Committed and Drawn)
  • Aerial Duels (Won and Lost)
  • Cards (Yellow and Red)
  • Goalkeeper Statistics

Sample Game Statistics

{
  "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
}

Database Initialization Details

The database is automatically initialized using init_db() which:

  1. Creates a user-specific data directory
  2. Installs a pre-configured SQLite database
  3. Seeds initial league data
  4. Sets up all required tables and relationships
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

Supported Leagues

The database is seeded with these leagues by default:

  • Premier League
  • La Liga
  • Serie A
  • Bundesliga
  • Ligue 1
  • EFL Championship

Notes

  • The Database contains latest data up to a specific data. To update the database with more information. Invoke update_data_set method.
  • All statistics are sourced from official match reports
  • Position groups (FW, MF, DF) are determined by primary player positions
  • The database maintains complete match history since the 2017-2018 season
  • Updates are rate-limited (4 secs) to respect data source restrictions

RankingTable

RankingTable Fetches Team ranking data for a given season and league.

Supported Leagues

  • Premier League
  • Ligue 1
  • La Liga
  • Serie A
  • Bundesliga

Supported Oldest Seasons

  • Premier League : 1947,
  • La Liga: 1929,
  • Serie A: 1929,
  • Ligue 1: 1945,
  • Bundesliga: 1963,

find_season_limit can be invoked to find the oldest supported seasons in RankingTable class

Usage

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")

Core Features

get_ranking_list() -> list

Retrieves the current Premier League ranking data in list format.

  • Returns: List containing the processed ranking data.
  • Example: 
    from premier_league import RankingTable
ranking = RankingTable().get_ranking_list()

Export Methods

get_ranking_csv(file_name: str, header: str = None) -> None

Exports the ranking data to a CSV file.

  • Parameters:
    • file_name (str): Name of the output file (without extension)
    • header (str, optional): Header to include in the CSV file
  • Example: 
    from 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) -> None

Exports the ranking data to a JSON file.

  • Parameters:
    • file_name (str): Name of the output file (without extension)
    • header (str, optional): Header to use as the parent key in the JSON structure
  • Example: 
    from 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) -> None

Generates a formatted PDF file containing the Premier League ranking table.

  • Parameters:
    • file_name (str): Name of the output file (without extension)
  • Features:
    • Color-coded rows for European qualification spots
    • Relegation zone highlighting
    • Centered title with season information
  • Example: 
    from premier_league import RankingTable
ranking = RankingTable()
ranking.get_ranking_pdf("premier_league_standings")

Data Format

The ranking data is structured as a list of lists, where each inner list contains:

  1. Position
  2. Team name
  3. Matches played
  4. Wins
  5. Draws
  6. Losses
  7. Goals for
  8. Goals against
  9. Goal difference
  10. Points

Example:

[
    ["Position", "Team", "MP", "W", "D", "L", "GF", "GA", "GD", "Points"],
    ["1", "Manchester City", "38", "32", "4", "2", "102", "31", "71", "100"],
    # ... more entries
]

Notes

  • The PDF generation includes color coding:
    • Green shades for European qualification spots
    • Red for relegation zones
    • Gray for header row
  • European qualification rules are handled differently for seasons before and after 2019-20
  • The class automatically handles special cases like the 1994-95 season when 4 teams were relegated

PlayerSeasonLeaders

PlayerSeasonLeaders is a specialized scraper for retrieving and processing player statistics, focusing on either goals or assists for a specific season.

Supported Leagues

  • Premier League
  • Ligue 1
  • La Liga
  • Serie A
  • Bundesliga

Supported Oldest Seasons

  • Premier League : 1997,
  • La Liga: 2008,
  • Serie A: 2010,
  • Ligue 1: 2010,
  • Bundesliga": 1988,

find_season_limit can be invoked to find the oldest supported seasons in SeasonPlayerLeaders class

Usage

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")

Core Features

get_top_stats_list(limit: int = None) -> list

Returns 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")

Data Format

Goals Statistics Format

List of lists with the following columns:

  1. Name
  2. Country
  3. Club
  4. Goals
  5. Goals Breakdown (In Play Goals + Penalties)

Example:

[
    ["Name", "Country", "Club", "Goals", "In Play Goals+Penalty"],
    ["Erling Haaland", "Norway", "Manchester City", "36", "30+6"],
    # ... more entries
]

Assists Statistics Format

List of lists with the following columns:

  1. Name
  2. Country
  3. Club
  4. Assists

Example:

[
    ["Name", "Country", "Club", "Assists"],
    ["Kevin De Bruyne", "Belgium", "Manchester City", "16"],
    # ... more entries
]

Notes

  • PDF export includes:
    • Gray header row
    • Gold highlighting for the top scorer/assister
    • Limited to top 20 players
    • A3 page size for better readability
  • Default limit for data retrieval is 100 entries
  • All export methods support optional headers and limits (except PDF which is fixed at top 20)

Transfers

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.

Supported Leagues

  • Premier League
  • Ligue 1
  • La Liga
  • Serie A
  • Bundesliga

Supported Oldest Seasons

  • Premier League : 1946,
  • La Liga: 1928,
  • Serie A: 1946,
  • Ligue 1: 1945,
  • Bundesliga: 1963,

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)

Usage

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()

Core Features

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) -> None

Display 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")

Data Format

Transfer Data Structure

Each transfer record contains the following columns:

  1. Date (format: "DD/MM")
  2. Name (player name)
  3. Position
  4. Club (previous/new club)

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
}

Notes

  • Team names are case-insensitive but must mirror official match names.
  • Raises TeamNotFoundError if specified team isn't found in the season
  • Data is scraped from worldfootball.net
  • Transfer dates are in DD/MM format
  • The print_transfer_table method uses PrettyTable for formatted console output
  • Export methods support three modes:
    • "both": Exports both incoming and outgoing transfers (default)
    • "in": Exports only incoming transfers
    • "out": Exports only outgoing transfers
  • Team names are stored in lowercase internally
  • The class automatically handles clubs with special characters or extended names
  • Transfer windows covered:
    • Summer transfer window
    • Winter transfer window
  • Position abbreviations follow standard football notation (MF, FW, DF, GK)

Flask API Docs

Premier League Players API Documentation

Table of Contents

🔍 Overview

Back to top

This 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.

📊 Endpoints

Get Top Scorers

GET /players/goals

Retrieve a list of top goalscorers in JSON format.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • limit (optional): Maximum number of players to return
  • league (optional): League specification (Defaults to Premier League)

Response

{
  "data": [
    {
      "name": "Erling Haaland",
      "country": "Norway",
      "club": "Manchester City",
      "goals": "36",
      "goals_breakdown": "30+6"
    }
  ]
}

Get Top Assists

GET /players/assists

Retrieve a list of top assist providers in JSON format.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • limit (optional): Maximum number of players to return
  • league (optional): League specification (Defaults to Premier League)

Response

{
  "data": [
    {
      "name": "Kevin De Bruyne",
      "country": "Belgium",
      "club": "Manchester City",
      "assists": "16"
    }
  ]
}

Export Scorers CSV

GET /players/goals/csv_file

Download top goalscorers data as a CSV file.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • filename (required): Name for the exported file (without extension)
  • header (optional): Custom header for the CSV file
  • limit (optional): Maximum number of players to return
  • league (optional): League name (defaults to "Premier League")

Export Assists CSV

GET /players/assists/csv_file

Download top assist providers data as a CSV file.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • filename (required): Name for the exported file (without extension)
  • header (optional): Custom header for the CSV file
  • limit (optional): Maximum number of players to return
  • league (optional): League name (defaults to "Premier League")

Export Scorers JSON

GET /players/goals/json_file

Download top goalscorers data as a JSON file.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • filename (required): Name for the exported file (without extension)
  • header (optional): Custom metadata for the JSON file
  • limit (optional): Maximum number of players to return
  • league (optional): League name (defaults to "Premier League")

Export Assists JSON

GET /players/assists/json_file

Download top assist providers data as a JSON file.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • filename (required): Name for the exported file (without extension)
  • header (optional): Custom metadata for the JSON file
  • limit (optional): Maximum number of players to return
  • league (optional): League name (defaults to "Premier League")

🔧 Common Parameters

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

❌ Error Handling

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"
}

📝 Examples

Get Top 5 Scorers for 2023-2024

GET /players/goals?season=2023-2024&limit=5

Export Top 10 Assists to CSV

GET /players/assists/csv_file?limit=10&filename=top_assists&header=Premier League Assists

Export All Scorers to JSON

GET /players/goals/json_file?filename=goalscorers&header=Goal Statistics

Using cURL

# 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"

Premier League Rankings API Documentation

Table of Contents

🔍 Overview Ranking

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.

📊 Endpoints /Ranking

Get Standings

GET /ranking

Retrieve detailed Premier League standings with comprehensive team statistics.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • header (optional): Include additional metadata in response
  • league (optional): League specification (Defaults to Premier League)

Response

{
  "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 Simple Table

GET /ranking/table

Retrieve a simplified version of the league standings.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • league (optional): League specification (Defaults to Premier League)

Response

{
  "data": [
    ["Pos", "Team", "P", "W", "D", "L", "GF", "GA", "GD", "Pts"],
    [1, "Arsenal", 38, 25, 8, 5, 88, 43, 45, 83]
  ]
}

Export CSV

GET /ranking/csv_file

Download Premier League standings as a CSV file.

Query Parameters

  • 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)

Export JSON

GET /ranking/json_file

Download Premier League standings as a JSON file.

Query Parameters

  • 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)

Export PDF

GET /ranking/pdf_file

Download League standings as a formatted PDF file.

Query Parameters

  • 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)

🔧 Common Query Parameters

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

❌ Error Codes

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"
}

📝 Example

Get Current Season Standings

GET /ranking

Get Specific Season's Simple Table

GET /ranking/table?season=2023-2024

Export Standings to Different Formats

# 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

Using cURL

# 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"

Data Format Details

Full Standings Response Fields

  • position: Current league position
  • team: Team name
  • played: Games played
  • won: Games won
  • drawn: Games drawn
  • lost: Games lost
  • goals_for: Goals scored
  • goals_against: Goals conceded
  • goal_difference: Goal difference (GF - GA)
  • points: Total points

Premier League Transfers API Documentation

Table of Contents

🔍 Overview Transfers

This 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.

📊 Endpoints /Transfers

Get All Teams

GET /all_teams

Retrieve a list of all teams in the Premier League for a given season.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • league (optional): League specification (Defaults to Premier League)

Response

{
  "data": [
    "Arsenal",
    "Aston Villa",
    "Brighton",
    "Burnley",
    ...
  ]
}

Get Incoming Transfers

GET /transfers/in

Retrieve all incoming transfers for a specific team.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • team (required): Team name
  • league (optional): League specification (Defaults to Premier League)

Response

{
  "data": [
    {
      "date": "01/07",
      "name": "Kai Havertz",
      "position": "MF",
      "previous_club": "Chelsea"
    }
  ]
}

Get Outgoing Transfers

GET /transfers/out

Retrieve all outgoing transfers for a specific team.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • team (required): Team name
  • league (optional): League specification (Defaults to Premier League)

Response

{
  "data": [
    {
      "date": "30/06",
      "name": "Granit Xhaka",
      "position": "MF",
      "new_club": "Bayer Leverkusen"
    }
  ]
}

Export Transfers CSV

GET /transfers/csv_file

Download transfer data as a CSV file.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • team (required): Team name
  • filename (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")

Export Transfers JSON

GET /transfers/json_file

Download transfer data as a JSON file.

Query Parameters

  • season (optional): Season identifier (e.g., "2023-2024")
  • team (required): Team name
  • filename (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")

🔧 Common API Parameters

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

❌ Error Code

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"
}

📝 Sample

Get All Teams for Current Season

GET /all_teams

Get Arsenal's Incoming Transfers

GET /transfers/in?team=Arsenal

Export Complete Transfer History

GET /transfers/csv_file?team=Manchester%20United&filename=united_transfers&transfer_type=both

Using cURL

# 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"

Data Format Details

Transfer Record Fields

  • date: Transfer date (DD/MM format)
  • name: Player name
  • position: Player position (e.g., MF, FW, DF, GK)
  • previous_club/new_club: Club involved in the transfer

File Export Features

  • CSV exports include headers
  • JSON exports are properly formatted
  • Filenames are sanitized for security
  • Support for splitting incoming/outgoing transfers

Lambda

All 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

Setup

  1. Get a Valid AWS Account and the following IAM Role.
- s3:PutObject
- s3:GetObject
  1. Create a S3 Bucket on the AWS Console with a name
  2. Install the Required Serverless Framework
npm install -g serverless
npm install -g serverless-python-requirements
  1. Run the following command to deploy and specify S3 bucket name, AWS Profile and the Region. (If no S3 Bucket name is specified, it defaults to premier-league-bucket)
S3_BUCKET_NAME=${s3 bucket name} python -m premier_league.lambda_functions.deploy_premier_league --aws-profile ${AWS IAM Account name} --region ${Your Region}
  1. API Endpoints information will show up once a Successful Deployment has been done.

About

Python Library For European Football

pypi.org/project/premier-league/

Topics

flask gunicorn soccer python3 premier-league flask-api reportlab-pdf reportlab-python

Resources

Readme

License

View license
Activity

Stars

6 stars

Watchers

2 watching

Forks

2 forks
Report repository

Releases 7

v1.0.4 Release Latest
May 15, 2025
+ 6 releases

Contributors 2

  •  
  •  

Languages