### Install EasySoccerData

Source: https://github.com/manucabral/easysoccerdata/blob/main/README.md

Install the package using pip.

```bash
pip install EasySoccerData
```

--------------------------------

### Retrieve Match Lineups with SofascoreClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Get confirmed lineups, formations, and player details for a specific match.

```python
import esd

client = esd.SofascoreClient()

# Get a live match
matches = client.get_events(live=True)
match = matches[0]

print(f"{match.home_team.name} vs {match.away_team.name}")

# Get lineups
lineups = client.get_match_lineups(match.id)
print(f"Confirmed lineups: {lineups.confirmed}")

# Home team lineup
print(f"\nFORMATION {match.home_team.name}: {lineups.home.formation}")
for player in lineups.home.players:
    if not player.substitute:  # Only starting players
        info = player.info
        print(f"{info.name} | Position: {info.position} | Number: {info.shirt_number}")

# Away team lineup
print(f"\nFORMATION {match.away_team.name}: {lineups.away.formation}")
for player in lineups.away.players:
    if not player.substitute:
        info = player.info
        print(f"{info.name} | Position: {info.position} | Number: {info.jersey_number}")
```

--------------------------------

### Initialize FBref Client and Get Matches

Source: https://github.com/manucabral/easysoccerdata/blob/main/README.md

Initialize the FBref client and retrieve match data. Ensure the 'esd' library is imported.

```python
import esd

client = esd.FBrefClient()
matchs = client.get_matchs()
for match in matchs:
    print(match)
```

--------------------------------

### Initialize Promiedos Client and Get Events

Source: https://github.com/manucabral/easysoccerdata/blob/main/README.md

Initialize the Promiedos client and retrieve event data. Ensure the 'esd' library is imported.

```python
import esd

client = esd.PromiedosClient()
events = client.get_events()
for event in events:
    print(event)
```

--------------------------------

### FBrefClient - Get Match Details

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Fetches detailed match report information from FBref including advanced statistics.

```APIDOC
## FBrefClient - Get Match Details

### Description
Fetches detailed match report information from FBref including advanced statistics.

### Method
GET

### Endpoint
/fbref/match/{matchId}/details

### Parameters
#### Path Parameters
- **matchId** (string) - Required - The ID of the match to retrieve details for.
#### Query Parameters
- **language** (string) - Optional - The language preference for the data (e.g., "en"). Defaults to "en".

### Request Example
```python
import esd

client = esd.FBrefClient(language="en")
matches = client.get_matchs(date="2025-03-11")
match = matches[0]
details = client.get_match_details(match.id)

print(f"Match Details for: {match.home_team} vs {match.away_team}")
print(details)
```

### Response
#### Success Response (200)
- **details** (object) - An object containing detailed match report information, including advanced statistics.

#### Response Example
```json
{
  "match_id": "match_id_123",
  "home_team": "Team A",
  "away_team": "Team B",
  "statistics": {
    "possession": "60%",
    "shots": 15,
    "shots_on_target": 7
  }
}
```
```

--------------------------------

### Initialize Sofascore Client and Get Live Events

Source: https://github.com/manucabral/easysoccerdata/blob/main/README.md

Initialize the Sofascore client and retrieve live events. Ensure the 'esd' library is imported.

```python
import esd

client = esd.SofascoreClient()
events = client.get_events(live=True)
for event in events:
    print(event)
```

--------------------------------

### SofascoreClient - Get Match Comments

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Fetches live text commentary for a match including goals, cards, and key events.

```APIDOC
## SofascoreClient - Get Match Comments

### Description
Fetches live text commentary for a match including goals, cards, and key events.

### Method
GET

### Endpoint
/sofascore/match/{matchId}/comments

### Parameters
#### Path Parameters
- **matchId** (integer) - Required - The ID of the match to retrieve comments for.

### Request Example
```python
from esd.sofascore import SofascoreClient

client = SofascoreClient()
comments = client.get_match_comments(13511924)
for comment in comments:
    print(f"{comment.time}' {comment.text}")
```

### Response
#### Success Response (200)
- **comments** (array) - A list of comment objects, each containing 'time' and 'text'.

#### Response Example
```json
[
  {
    "time": "0'",
    "text": "Match ends, Atletico Madrid 1(2), Real Madrid 0(4)."
  },
  {
    "time": "127'",
    "text": "Goal! Antonio Rüdiger (Real Madrid) converts the penalty..."
  }
]
```
```

--------------------------------

### Get Soccer Events by Date with PromiedosClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves events organized by league for a given date. Provides access to match scores, status, and goal details.

```python
import esd

client = esd.PromiedosClient()

# Get today's events
events = client.get_events()

for event in events:
    print(f"League: {event.league.name} - {event.date}")

    for match in event.matches:
        print(f"  {match.home_team.name} {match.scores.home} - {match.scores.away} {match.away_team.name}")
        print(f"  Status: {match.status.name} - {match.time_to_display}")

        # Print goals
        goals = match.home_team.goals + match.away_team.goals
        for goal in goals:
            print(f"    Goal: {goal.full_name} ({goal.time_to_display}, penalty: {goal.is_penalty})")
        print("-----------------")
```

--------------------------------

### FBrefClient - Get Matches with xG Data

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves match results with expected goals (xG) statistics and match notes from FBref.

```APIDOC
## FBrefClient - Get Matches with xG Data

### Description
Retrieves match results with expected goals (xG) statistics and match notes from FBref.

### Method
GET

### Endpoint
/fbref/matches

### Parameters
#### Query Parameters
- **date** (string) - Optional - The date to retrieve matches for (YYYY-MM-DD). Defaults to today.
- **language** (string) - Optional - The language preference for the data (e.g., "en"). Defaults to "en".

### Request Example
```python
import esd

client = esd.FBrefClient(language="en")
matches = client.get_matchs(date="2025-03-11")

for match in matches:
    print(f"{match.home_team} {match.home_score} - {match.away_score} {match.away_team}")
    print(f"xG: {match.home_xg} - {match.away_xg}")
    if match.notes:
        print(f"Notes: {match.notes}")
    print()

today_matches = client.get_matchs() # No date defaults to today
```

### Response
#### Success Response (200)
- **matches** (array) - A list of match objects, each containing 'home_team', 'away_team', 'home_score', 'away_score', 'home_xg', 'away_xg', and 'notes'.

#### Response Example
```json
[
  {
    "home_team": "Team A",
    "away_team": "Team B",
    "home_score": 2,
    "away_score": 1,
    "home_xg": 1.5,
    "away_xg": 0.8,
    "notes": "Late goal decided the match."
  }
]
```
```

--------------------------------

### Retrieve Match Shots and xG with SofascoreClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Get shot data including expected goals (xG) and timing for a specific match.

```python
from esd import SofascoreClient, SofascoreTypes

client = SofascoreClient()

match_id = 13511931  # PSG vs Liverpool

shots = client.get_match_shots(match_id)

for shot in shots:
    print(f"Player: {shot.player.short_name}")
    print(f"xG: {shot.xg}, xGOT: {shot.xg_got}")
    print(f"Body part: {shot.body_part}, Time: {shot.time}'")
    print("---")
```

--------------------------------

### SofascoreClient - Get Team Players

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves all players from a team including contract details, position, and biographical information.

```APIDOC
## SofascoreClient - Get Team Players

### Description
Retrieves all players from a team including contract details, position, and biographical information.

### Method
GET

### Endpoint
/sofascore/team/{teamId}/players

### Parameters
#### Path Parameters
- **teamId** (integer) - Required - The ID of the team to retrieve players for.

### Request Example
```python
import esd
import datetime

client = esd.SofascoreClient()
teams = client.search("Liverpool", entity=esd.SofascoreTypes.EntityType.TEAM)
liverpool = teams[0]
players = client.get_team_players(liverpool.id)

for player in players:
    print("---------------------------------")
    print(f"{player.name}, position {player.position}, number {player.jersey_number}")
    date_of_birth = datetime.datetime.fromtimestamp(player.date_of_birth).strftime("%B %Y")
    contract_until = datetime.datetime.fromtimestamp(player.contract_until).strftime("%B %Y")
    print(f"Date of birth: {date_of_birth}")
    print(f"Contract until: {contract_until}")
```

### Response
#### Success Response (200)
- **players** (array) - A list of player objects, each containing 'name', 'position', 'jersey_number', 'date_of_birth', and 'contract_until'.

#### Response Example
```json
[
  {
    "name": "Mohamed Salah",
    "position": "Forward",
    "jersey_number": 11,
    "date_of_birth": 562272000,
    "contract_until": 1735689600
  }
]
```
```

--------------------------------

### PromiedosClient - Get Events by Date

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves all soccer events organized by league for a given date from Promiedos (Spanish-language source).

```APIDOC
## PromiedosClient - Get Events by Date

### Description
Retrieves all soccer events organized by league for a given date from Promiedos (Spanish-language source).

### Method
GET

### Endpoint
/promiedos/events

### Parameters
#### Query Parameters
- **date** (string) - Optional - The date to retrieve events for (YYYY-MM-DD). Defaults to today.

### Request Example
```python
import esd

client = esd.PromiedosClient()
events = client.get_events()

for event in events:
    print(f"League: {event.league.name} - {event.date}")
    for match in event.matches:
        print(f"  {match.home_team.name} {match.scores.home} - {match.scores.away} {match.away_team.name}")
        print(f"  Status: {match.status.name} - {match.time_to_display}")
        goals = match.home_team.goals + match.away_team.goals
        for goal in goals:
            print(f"    Goal: {goal.full_name} ({goal.time_to_display}, penalty: {goal.is_penalty})")
        print("-----------------")
```

### Response
#### Success Response (200)
- **events** (array) - A list of event objects, organized by league. Each event contains 'league', 'date', and 'matches'. Each match object includes details like 'home_team', 'away_team', 'scores', 'status', 'time_to_display', and 'goals'.

#### Response Example
```json
[
  {
    "league": {"name": "La Liga"},
    "date": "2023-10-27",
    "matches": [
      {
        "home_team": {"name": "Real Madrid"},
        "away_team": {"name": "Barcelona"},
        "scores": {"home": 2, "away": 1},
        "status": {"name": "Finished"},
        "time_to_display": "FT",
        "home_team_goals": [{"full_name": "Benzema", "time_to_display": "45'+1", "is_penalty": false}],
        "away_team_goals": [{"full_name": "Torres", "time_to_display": "70'", "is_penalty": false}]
      }
    ]
  }
]
```
```

--------------------------------

### SofascoreClient - Get Tournament Brackets

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Fetches knockout stage brackets for cup competitions with round details and match scores.

```APIDOC
## SofascoreClient - Get Tournament Brackets

### Description
Fetches knockout stage brackets for cup competitions with round details and match scores.

### Method
GET

### Endpoint
/sofascore/tournament/{tournamentId}/season/{seasonId}/brackets

### Parameters
#### Path Parameters
- **tournamentId** (integer) - Required - The ID of the tournament.
- **seasonId** (integer) - Required - The ID of the season.

### Request Example
```python
import esd

client = esd.SofascoreClient()
brackets = client.get_tournament_brackets(7, 61644)
bracket = brackets[0]

print(f"{bracket.name}")
print(f"Current round: {bracket.current_round}")

for round in bracket.rounds:
    if round.order < bracket.current_round:
        continue
    print(f"\nRound {round.order}: {round.description} ({len(round.blocks)} matches)")
    for block in round.blocks:
        if len(block.events) > 0:
            match = client.get_event(block.events[0])
            print(f"  {match.home_team.name} {block.home_team_score} - {block.away_team_score} {match.away_team.name}")
```

### Response
#### Success Response (200)
- **brackets** (array) - A list of bracket objects. Each bracket contains 'name', 'current_round', and 'rounds'. Each round contains 'order', 'description', and 'blocks'. Each block contains 'events' and team scores.

#### Response Example
```json
[
  {
    "name": "UEFA Champions League",
    "current_round": 5,
    "rounds": [
      {
        "order": 5,
        "description": "Final",
        "blocks": [
          {
            "events": ["match_id_1"],
            "home_team_score": 1,
            "away_team_score": 0
          }
        ]
      }
    ]
  }
]
```
```

--------------------------------

### Get Tournament Standings with SofascoreClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves league table standings for a specific tournament and season. Returns a list of standing tables.

```python
import esd

client = esd.SofascoreClient()

# UEFA Champions League tournament ID: 7, Season ID: 61644
uefa_tournament_id = 7
season_id = 61644

standings = client.get_tournament_standings(uefa_tournament_id, season_id)

# UEFA Champions League has one standing table
current_standing = standings[0]

for item in current_standing.items:
    print(f"{item.position}. {item.team.name} - {item.points} points")
    print(f"   Matches: {item.matches} | W: {item.wins} D: {item.draws} L: {item.losses}")
```

--------------------------------

### SofascoreClient - Get Tournament Standings

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves league table standings for a tournament season including points, wins, draws, losses, and goal differences.

```APIDOC
## SofascoreClient - Get Tournament Standings

### Description
Retrieves league table standings for a tournament season including points, wins, draws, losses, and goal differences.

### Method
GET

### Endpoint
/sofascore/tournament/{tournamentId}/season/{seasonId}/standings

### Parameters
#### Path Parameters
- **tournamentId** (integer) - Required - The ID of the tournament.
- **seasonId** (integer) - Required - The ID of the season.

### Request Example
```python
import esd

client = esd.SofascoreClient()
standings = client.get_tournament_standings(7, 61644)
current_standing = standings[0]

for item in current_standing.items:
    print(f"{item.position}. {item.team.name} - {item.points} points")
    print(f"   Matches: {item.matches} | W: {item.wins} D: {item.draws} L: {item.losses}")
```

### Response
#### Success Response (200)
- **standings** (array) - A list of standing tables for the season. Each table contains 'items' (teams) with details like 'position', 'team', 'points', 'wins', 'draws', and 'losses'.

#### Response Example
```json
[
  {
    "items": [
      {
        "position": 1,
        "team": {"name": "Real Madrid"},
        "points": 75,
        "wins": 23,
        "draws": 6,
        "losses": 5
      }
    ]
  }
]
```
```

--------------------------------

### Fetch In-Progress Match Details with Stats

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves detailed match information such as formations, possession, and card counts for matches currently in progress.

```python
import esd

client = esd.PromiedosClient()
events = client.get_events()

for event in events:
    for match in event.matches:
        # Only process in-progress matches
        if match.status.value != esd.PromiedosTypes.MatchStatus.IN_PROGRESS:
            continue

        print(f"League: {event.league.name}")
        print(f"{match.home_team.name} {match.scores.home} - {match.scores.away} {match.away_team.name}")
        print(f"Status: {match.status.name} - {match.time_to_display}")

        # Get full match details
        full_match = client.get_match(match.id)

        print(f"Formations: {full_match.players.lineups.home_team.formation} - {full_match.players.lineups.away_team.formation}")
        print(f"Possession: {full_match.stats.possession.home_value} - {full_match.stats.possession.away_value}")
        print(f"Shots: {full_match.stats.total_shots.home_value} - {full_match.stats.total_shots.away_value}")
        print(f"Yellow/Red Cards: {full_match.stats.yellow_cards.home_value}/{full_match.stats.red_cards.home_value} - {full_match.stats.yellow_cards.away_value}/{full_match.stats.red_cards.away_value}")
        print("-------------------")
```

--------------------------------

### Fetch Match Statistics with SofascoreClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieve detailed performance metrics like possession and shots for a specific match ID.

```python
import esd

client = esd.SofascoreClient()

# Get live match first
events = client.get_events(live=True)
match = events[0]

# Fetch detailed match statistics
details = client.get_match_stats(match.id)

print(f"Match: {match.home_team.name} vs {match.away_team.name}")
print(f"Possession: {details.all.match_overview.ball_possession.home_value}% - {details.all.match_overview.ball_possession.away_value}%")
print(f"Shots on Goal: {details.all.shots.shots_on_goal.home_value} - {details.all.shots.shots_on_goal.away_value}")
```

--------------------------------

### Retrieve Live Events with SofascoreClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Fetch currently live soccer matches or scheduled events for a specific date.

```python
import esd

client = esd.SofascoreClient()

# Get all live events
events = client.get_events(live=True)

for event in events:
    print(f"Match ID: {event.id}, Status: {event.status.description}")
    print(f"Time: {event.current_elapsed_minutes}' (total: {event.total_elapsed_minutes}')")
    print(f"Board: {event.home_team.name} {event.home_score.current} - {event.away_score.current} {event.away_team.name}")
    print("---")

# Get events for a specific date
scheduled_events = client.get_events(date="2025-03-15")
for event in scheduled_events:
    print(f"{event.home_team.name} vs {event.away_team.name}")
```

--------------------------------

### Retrieve Matches with xG Data via FBrefClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Fetches match results including expected goals (xG) statistics. Supports filtering by date or defaulting to the current day.

```python
import esd

# Initialize with language preference
client = esd.FBrefClient(language="en")

# Get matches for a specific date
matches = client.get_matchs(date="2025-03-11")

for match in matches:
    print(f"{match.home_team} {match.home_score} - {match.away_score} {match.away_team}")
    print(f"xG: {match.home_xg} - {match.away_xg}")
    if match.notes:
        print(f"Notes: {match.notes}")
    print()

# Get today's matches
today_matches = client.get_matchs()  # No date defaults to today
```

--------------------------------

### Fetch Match Comments with SofascoreClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves live text commentary for a specific match ID. Requires the SofascoreClient initialized from the esd.sofascore module.

```python
from esd.sofascore import SofascoreClient

client = SofascoreClient()

# Match ID for Atletico Madrid vs Real Madrid
comments = client.get_match_comments(13511924)

for comment in comments:
    print(f"{comment.time}' {comment.text}")

# Output example:
# 0' Match ends, Atletico Madrid 1(2), Real Madrid 0(4).
# 127' Goal! Antonio Rüdiger (Real Madrid) converts the penalty...
```

--------------------------------

### Fetch Detailed Match Reports with FBrefClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves advanced statistics for a specific match using its ID. Requires a match ID obtained from the get_matchs method.

```python
import esd

client = esd.FBrefClient(language="en")

# Get match list first to find match ID
matches = client.get_matchs(date="2025-03-11")
match = matches[0]

# Get detailed match report
details = client.get_match_details(match.id)

print(f"Match Details for: {match.home_team} vs {match.away_team}")
print(details)
```

--------------------------------

### Fetch Tournament Brackets with SofascoreClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves knockout stage brackets for cup competitions. Iterates through rounds and blocks to access individual match events.

```python
import esd

client = esd.SofascoreClient()

uefa_tournament_id = 7
season_id = 61644

brackets = client.get_tournament_brackets(uefa_tournament_id, season_id)

# UEFA Champions League has one bracket
bracket = brackets[0]

print(f"{bracket.name}")
print(f"Current round: {bracket.current_round}")

for round in bracket.rounds:
    if round.order < bracket.current_round:
        continue  # Skip past rounds

    print(f"\nRound {round.order}: {round.description} ({len(round.blocks)} matches)")

    for block in round.blocks:
        if len(block.events) > 0:
            match = client.get_event(block.events[0])
            print(f"  {match.home_team.name} {block.home_team_score} - {block.away_team_score} {match.away_team.name}")
```

--------------------------------

### Retrieve Team Players with SofascoreClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Fetches player rosters for a team, including biographical data and contract information. Requires searching for the team entity first to obtain an ID.

```python
import esd
import datetime

client = esd.SofascoreClient()

# Search for a team
teams = client.search("Liverpool", entity=esd.SofascoreTypes.EntityType.TEAM)
liverpool = teams[0]  # Liverpool FC

# Get team players
players = client.get_team_players(liverpool.id)

for player in players:
    print("---------------------------------")
    print(f"{player.name}, position {player.position}, number {player.jersey_number}")

    date_of_birth = datetime.datetime.fromtimestamp(player.date_of_birth).strftime("%B %Y")
    contract_until = datetime.datetime.fromtimestamp(player.contract_until).strftime("%B %Y")

    print(f"Date of birth: {date_of_birth}")
    print(f"Contract until: {contract_until}")
```

--------------------------------

### Retrieve Detailed Match Events

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Fetches match events like goals, cards, and substitutions, categorized by match half for a specific match ID.

```python
import esd

client = esd.PromiedosClient()

# Get match by ID
match = client.get_match("ediedag")  # Liverpool vs PSG

print(f"{match.home_team.short_name} {match.scores.home} - {match.scores.away} {match.away_team.short_name}")
print(f"{match.status.name} - {match.current_time}'")

print("\nFirst Half:")
for event in match.events.first_half:
    print(f"  {event.time}' - {event.details} ({event.event_type})")

print("\nSecond Half:")
for event in match.events.second_half:
    print(f"  {event.time}' - {event.details} ({event.event_type})")

print("\nExtra Time:")
for event in match.events.extra_time:
    print(f"  {event.time}' - {event.details} ({event.event_type})")

print("\nPenalties:")
for event in match.events.penalties:
    print(f"  {event.details} ({event.event_type})")
```

--------------------------------

### Search Entities with SofascoreClient

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Search for matches, teams, players, or tournaments using a query string and entity type filtering.

```python
import esd
import datetime

client = esd.SofascoreClient()

# Search for matches involving Manchester United
matches = client.search("Manchester United", entity=esd.SofascoreTypes.EntityType.EVENT)
for match in matches:
    print(f"Match ID: {match.id}, Status: {match.status.description}")
    print(f"{match.home_team.name} vs {match.away_team.name}")
    if match.status.type == "notstarted":
        start_time = datetime.datetime.fromtimestamp(match.start_timestamp)
        print(f"Start time: {start_time}")
    print("--------------------")

# Search for teams
teams = client.search("Liverpool", entity=esd.SofascoreTypes.EntityType.TEAM)
for team in teams:
    print(f"Team ID: {team.id}, Name: {team.name}, Slug: {team.slug}")

# Search all entity types
all_results = client.search("Barcelona", entity=esd.SofascoreTypes.EntityType.ALL)
```

--------------------------------

### Fetch Tournament Matches

Source: https://context7.com/manucabral/easysoccerdata/llms.txt

Retrieves all matches for a specific tournament, filtered by stage or round using the tournament ID.

```python
from esd import PromiedosClient, PromiedosTypes

client = PromiedosClient()

# "fhc" is the ID for UEFA Champions League
tournament = client.get_tournament("fhc")

print(f"Tournament: {tournament.league.name} ({tournament.league.slug})")

# Get current stage
stage = tournament.current_stage()
print(f"Current stage: {stage.name}")

# Get matches for the current stage
matches = client.get_tournament_matchs(tournament.league.id, stage.id)

print("\nMatches:")
for match in matches:
    print(f"  {match.home_team.name} vs {match.away_team.name}")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.