transfermarkt-api 5.0.0__py3-none-any.whl

transfermarkt_api/schemas/countries.py

@@ -0,0 +1,16 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class Country(TransfermarktBaseModel):
+    id: int
+    name: str
+    fifa_code: Optional[str] = None
+    confederation_id: Optional[int] = None
+    flag_url: Optional[str] = None
+    is_historical: bool
+
+
+class Countries(TransfermarktBaseModel, AuditMixin):
+    countries: list[Country]

transfermarkt_api/schemas/games/__init__.py

@@ -0,0 +1,83 @@
+from datetime import datetime
+from typing import Literal, Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class GameEntity(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+
+
+class GamePlayer(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    shirt_number: Optional[int] = None
+    position: Optional[str] = None
+    is_captain: bool = False
+
+
+class GameTeamStats(TransfermarktBaseModel):
+    possession: Optional[float] = None
+    shots: Optional[int] = None
+    shots_on_target: Optional[int] = None
+    shots_off_target: Optional[int] = None
+    shots_blocked: Optional[int] = None
+    passes: Optional[int] = None
+    accurate_passes: Optional[int] = None
+    tackles: Optional[int] = None
+    tackles_won: Optional[int] = None
+    clearances: Optional[int] = None
+    saves: Optional[int] = None
+    offsides: Optional[int] = None
+    corners: Optional[int] = None
+    fouls_committed: Optional[int] = None
+    fouls_suffered: Optional[int] = None
+    yellow_cards: Optional[int] = None
+    second_yellow_cards: Optional[int] = None
+    red_cards: Optional[int] = None
+    penalties_won: Optional[int] = None
+    penalties_saved: Optional[int] = None
+    own_goals: Optional[int] = None
+
+
+class GameSide(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    score: Optional[int] = None
+    formation: Optional[str] = None
+    coach: Optional[GameEntity] = None
+    stats: Optional[GameTeamStats] = None
+    starting_lineup: list[GamePlayer]
+    substitutes: list[GamePlayer]
+
+
+class GameScore(TransfermarktBaseModel):
+    home: int
+    away: int
+
+
+class GameEvent(TransfermarktBaseModel):
+    type: Literal["goal", "card", "substitution"]
+    minute: Optional[int] = None
+    added_time: Optional[int] = None
+    club_id: Optional[str] = None
+    player: Optional[GameEntity] = None
+    related_player: Optional[GameEntity] = None
+    card: Optional[Literal["yellow", "secondYellow", "red"]] = None
+    score: Optional[GameScore] = None
+
+
+class Game(TransfermarktBaseModel, AuditMixin):
+    id: str
+    url: Optional[str] = None
+    competition: GameEntity
+    season_id: Optional[str] = None
+    season: Optional[str] = None
+    match_day: Optional[int] = None
+    date: Optional[datetime] = None
+    stadium: Optional[GameEntity] = None
+    attendance: Optional[int] = None
+    home: GameSide
+    away: GameSide
+    events: list[GameEvent]

transfermarkt_api/schemas/players/__init__.py

@@ -0,0 +1,9 @@
+from transfermarkt_api.schemas.players.absences import PlayerAbsences as PlayerAbsences
+from transfermarkt_api.schemas.players.injuries import PlayerInjuries as PlayerInjuries
+from transfermarkt_api.schemas.players.market_value import PlayerMarketValue as PlayerMarketValue
+from transfermarkt_api.schemas.players.matches import PlayerMatches as PlayerMatches
+from transfermarkt_api.schemas.players.national_career import PlayerNationalCareer as PlayerNationalCareer
+from transfermarkt_api.schemas.players.profile import PlayerProfile as PlayerProfile
+from transfermarkt_api.schemas.players.search import PlayerSearch as PlayerSearch
+from transfermarkt_api.schemas.players.stats import PlayerStats as PlayerStats
+from transfermarkt_api.schemas.players.transfers import PlayerTransfers as PlayerTransfers

transfermarkt_api/schemas/players/absences.py

@@ -0,0 +1,22 @@
+from datetime import date
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class Absence(TransfermarktBaseModel):
+    season: Optional[str] = None
+    reason: Optional[str] = None
+    competition_id: Optional[str] = None
+    competition_name: Optional[str] = None
+    from_date: Optional[date] = None
+    until_date: Optional[date] = None
+    days: Optional[int] = None
+    games_missed: Optional[int] = None
+
+
+class PlayerAbsences(TransfermarktBaseModel, AuditMixin):
+    id: str
+    page_number: int
+    last_page_number: int
+    absences: list[Absence]

transfermarkt_api/schemas/players/injuries.py

@@ -0,0 +1,20 @@
+from datetime import date
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class Injury(TransfermarktBaseModel):
+    season: Optional[str] = None
+    injury: Optional[str] = None
+    from_date: Optional[date] = None
+    until_date: Optional[date] = None
+    days: Optional[int] = None
+    games_missed: Optional[int] = None
+
+
+class PlayerInjuries(TransfermarktBaseModel, AuditMixin):
+    id: str
+    page_number: int
+    last_page_number: int
+    injuries: list[Injury]

transfermarkt_api/schemas/players/market_value.py

@@ -0,0 +1,19 @@
+from datetime import date
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class MarketValueHistory(TransfermarktBaseModel):
+    age: Optional[int] = None
+    date: date
+    club_id: Optional[str] = None
+    club_name: Optional[str] = None
+    market_value: Optional[int] = None
+
+
+class PlayerMarketValue(TransfermarktBaseModel, AuditMixin):
+    id: str
+    market_value: Optional[int] = None
+    market_value_history: list[MarketValueHistory]
+    ranking: Optional[dict[str, int]] = None

transfermarkt_api/schemas/players/matches.py

@@ -0,0 +1,56 @@
+from datetime import datetime
+from typing import Literal, Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class PlayerMatchEntity(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+
+
+class PlayerMatch(TransfermarktBaseModel):
+    game_id: str
+    date: Optional[datetime] = None
+    season: Optional[str] = None
+    competition: PlayerMatchEntity
+    match_day: Optional[int] = None
+    club: PlayerMatchEntity
+    opponent: PlayerMatchEntity
+    venue: Optional[Literal["home", "away", "neutral"]] = None
+    club_goals: Optional[int] = None
+    opponent_goals: Optional[int] = None
+    participation: Optional[str] = None
+    shirt_number: Optional[int] = None
+    is_captain: bool = False
+    position: Optional[str] = None
+    is_starting: bool = False
+    substituted_in_minute: Optional[int] = None
+    substituted_out_minute: Optional[int] = None
+    minutes_played: int = 0
+    team_points: Optional[int] = None
+    goals: int = 0
+    assists: int = 0
+    yellow_card: bool = False
+    second_yellow_card: bool = False
+    red_card: bool = False
+    own_goals: Optional[int] = None
+    penalty_goals: Optional[int] = None
+    penalties_missed: Optional[int] = None
+    penalties_saved: Optional[int] = None
+    shots: Optional[int] = None
+    shots_on_target: Optional[int] = None
+    passes: Optional[int] = None
+    accurate_passes: Optional[int] = None
+    tackles: Optional[int] = None
+    tackles_won: Optional[int] = None
+    fouls_committed: Optional[int] = None
+    fouls_suffered: Optional[int] = None
+    offsides: Optional[int] = None
+
+
+class PlayerMatches(TransfermarktBaseModel, AuditMixin):
+    id: str
+    page_number: int
+    last_page_number: int
+    matches: list[PlayerMatch]

transfermarkt_api/schemas/players/national_career.py

@@ -0,0 +1,21 @@
+from datetime import date
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class NationalTeam(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    appearances: Optional[int] = None
+    goals: Optional[int] = None
+    shirt_number: Optional[int] = None
+    is_captain: Optional[bool] = None
+    debut: Optional[date] = None
+    last_match: Optional[date] = None
+    status: Optional[str] = None
+
+
+class PlayerNationalCareer(TransfermarktBaseModel, AuditMixin):
+    id: str
+    national_teams: list[NationalTeam]

transfermarkt_api/schemas/players/profile.py

@@ -0,0 +1,81 @@
+import datetime
+from datetime import date
+from typing import Literal, Optional
+
+from pydantic import HttpUrl
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class PlayerPlaceOfBirth(TransfermarktBaseModel):
+    city: Optional[str] = None
+    country: Optional[str] = None
+
+
+class PlayerPosition(TransfermarktBaseModel):
+    main: Optional[str] = None
+    group: Optional[str] = None
+    other: list[str] = []
+
+
+class PlayerClub(TransfermarktBaseModel):
+    id: Optional[str] = None
+    name: Optional[str] = None
+    joined: Optional[date] = None
+    is_captain: Optional[bool] = None
+    contract_expires: Optional[date] = None
+    last_contract_renewal: Optional[date] = None
+    contract_option: Optional[str] = None
+    last_club_id: Optional[str] = None
+    last_club_name: Optional[str] = None
+
+
+class PlayerNationalTeam(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    shirt_number: Optional[str] = None
+    is_captain: Optional[bool] = None
+    debut: Optional[date] = None
+
+
+class PlayerDatedValue(TransfermarktBaseModel):
+    value: int
+    date: Optional[datetime.date] = None
+
+
+class PlayerMarketValueDetails(TransfermarktBaseModel):
+    last_updated: Optional[date] = None
+    trend: Optional[Literal["increased", "decreased", "unchanged"]] = None
+    previous: Optional[PlayerDatedValue] = None
+    highest: Optional[PlayerDatedValue] = None
+
+
+class PlayerAgent(TransfermarktBaseModel):
+    name: Optional[str] = None
+    url: Optional[str] = None
+
+
+class PlayerProfile(TransfermarktBaseModel, AuditMixin):
+    id: str
+    url: Optional[HttpUrl] = None
+    name: str
+    full_name: Optional[str] = None
+    name_in_home_country: Optional[str] = None
+    image_url: Optional[HttpUrl] = None
+    date_of_birth: Optional[date] = None
+    date_of_death: Optional[date] = None
+    place_of_birth: PlayerPlaceOfBirth
+    age: Optional[int] = None
+    height: Optional[int] = None
+    citizenship: list[str]
+    is_retired: bool
+    retired_since: Optional[date] = None
+    position: PlayerPosition
+    foot: Optional[str] = None
+    shirt_number: Optional[str] = None
+    club: PlayerClub
+    national_team: Optional[PlayerNationalTeam] = None
+    market_value: Optional[int] = None
+    market_value_details: Optional[PlayerMarketValueDetails] = None
+    agent: Optional[PlayerAgent] = None
+    outfitter: Optional[str] = None

transfermarkt_api/schemas/players/search.py

@@ -0,0 +1,25 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class PlayerSearchClub(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+
+
+class PlayerSearchResult(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    position: Optional[str] = None
+    club: Optional[PlayerSearchClub] = None
+    age: Optional[int] = None
+    nationalities: list[str]
+    market_value: Optional[int] = None
+
+
+class PlayerSearch(TransfermarktBaseModel, AuditMixin):
+    query: str
+    page_number: int
+    last_page_number: int
+    results: list[PlayerSearchResult]

transfermarkt_api/schemas/players/stats.py

@@ -0,0 +1,24 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class PlayerStat(TransfermarktBaseModel):
+    competition_id: str
+    competition_name: Optional[str] = None
+    season_id: str
+    club_id: str
+    appearances: int
+    goals: int
+    assists: int
+    yellow_cards: int
+    second_yellow_cards: int
+    red_cards: int
+    minutes_played: int
+    goals_conceded: int
+    clean_sheets: int
+
+
+class PlayerStats(TransfermarktBaseModel, AuditMixin):
+    id: str
+    stats: list[PlayerStat]

transfermarkt_api/schemas/players/transfers.py

@@ -0,0 +1,38 @@
+import datetime
+from typing import Literal, Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class PlayerTransferLeague(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+
+
+class PlayerTransferClub(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    country_id: Optional[str] = None
+    country_name: Optional[str] = None
+    league: Optional[PlayerTransferLeague] = None
+
+
+class PlayerTransfer(TransfermarktBaseModel):
+    id: str
+    club_from: PlayerTransferClub
+    club_to: PlayerTransferClub
+    date: Optional[datetime.date] = None
+    upcoming: bool
+    transfer_type: Optional[Literal["transfer", "freeTransfer", "internal", "loan", "endOfLoan"]] = None
+    season: Optional[str] = None
+    market_value: Optional[int] = None
+    fee: Optional[int] = None
+    age: Optional[int] = None
+    contract_until: Optional[datetime.date] = None
+    remaining_contract_days: Optional[int] = None
+
+
+class PlayerTransfers(TransfermarktBaseModel, AuditMixin):
+    id: str
+    transfers: list[PlayerTransfer]
+    youth_clubs: list[str] = []

transfermarkt_api/services/achievements.py

@@ -0,0 +1,50 @@
+from transfermarkt_api.tfmkt import TfmktClient
+
+
+async def group_achievements(tfmkt: TfmktClient, data: dict) -> list[dict]:
+    """
+    Group upstream achievement records (one per title won) into titles with a count and per-season details.
+
+    Titles follow upstream's display order; details are most recent season first. Player records carry the club and
+    competition of each title; club records carry only the season, so those fields are null.
+    """
+    records_by_title: dict[int, list[dict]] = {}
+    for record in data.get("achievements") or []:
+        records_by_title.setdefault(record["id"], []).append(record)
+
+    aggregated = {entry["id"]: entry for entry in data.get("aggregated") or []}
+    titles = sorted(
+        records_by_title,
+        key=lambda title_id: ((aggregated.get(title_id) or {}).get("order", 10_000), title_id),
+    )
+
+    details = [record.get("details") or {} for records in records_by_title.values() for record in records]
+    clubs = await tfmkt.clubs(d.get("clubId") for d in details if d.get("clubId") not in (None, "", "0"))
+    competitions = await tfmkt.competitions(d.get("competitionId") for d in details if d.get("competitionId"))
+
+    def entity(entities: dict, entity_id: str | int | None) -> dict | None:
+        """Return `{id, name}` for a referenced club or competition, or None when there is no reference."""
+        if entity_id in (None, "", "0"):
+            return None
+        return {"id": str(entity_id), "name": entities.get(str(entity_id), {}).get("name")}
+
+    return [
+        {
+            "title": (
+                (aggregated.get(title_id) or {}).get("name") or records_by_title[title_id][0].get("name") or ""
+            ).strip(),
+            "count": len(records_by_title[title_id]),
+            "details": [
+                {
+                    "season": {
+                        "id": str(record["seasonId"]) if record.get("seasonId") is not None else None,
+                        "name": (record.get("season") or {}).get("display"),
+                    },
+                    "club": entity(clubs, (record.get("details") or {}).get("clubId")),
+                    "competition": entity(competitions, (record.get("details") or {}).get("competitionId")),
+                }
+                for record in sorted(records_by_title[title_id], key=lambda r: r.get("seasonId") or 0, reverse=True)
+            ],
+        }
+        for title_id in titles
+    ]

transfermarkt_api/services/clubs/achievements.py

@@ -0,0 +1,10 @@
+from transfermarkt_api.services.achievements import group_achievements
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+
+
+async def get_club_achievements(tfmkt: TfmktClient, club_id: str) -> dict:
+    """Club titles, including participations, with the seasons they were won."""
+    # the achievement route answers 200 with no data for unknown clubs; the club lookup gives a proper 404
+    _, data = await gather(tfmkt.club(club_id), tfmkt.club_achievements(club_id))
+    return {"id": club_id, "achievements": await group_achievements(tfmkt, data)}

transfermarkt_api/services/clubs/listing.py

@@ -0,0 +1,22 @@
+from transfermarkt_api.exceptions import NotFound, UpstreamError
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.reference import get_reference
+
+
+async def list_clubs(tfmkt: TfmktClient, country_id: int) -> dict:
+    """List the clubs available in the upstream country directory, preserving its order."""
+    reference = await get_reference(tfmkt)
+    country_name = reference.country_name(country_id)
+    if country_name is None:
+        raise NotFound(f"Country not found: {country_id}")
+
+    directory = await tfmkt.country_clubs(country_id)
+    if not isinstance(directory, dict) or not isinstance(directory.get("clubIds"), list):
+        raise UpstreamError(f"Unexpected upstream payload for /country/{country_id}/club")
+    club_ids = list(dict.fromkeys(str(club_id) for club_id in directory["clubIds"]))
+    clubs = await tfmkt.clubs(club_ids)
+    return {
+        "countryId": country_id,
+        "countryName": country_name,
+        "clubs": [{"id": club_id, "name": clubs.get(club_id, {}).get("name")} for club_id in club_ids],
+    }

transfermarkt_api/services/clubs/players.py

@@ -0,0 +1,88 @@
+from typing import Optional
+
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import (
+    current_assignment,
+    date_of_birth,
+    get_reference,
+    height_cm,
+    market_value_of,
+    nationality_ids,
+)
+
+
+async def get_club_players(tfmkt: TfmktClient, club_id: str, season_id: Optional[str] = None) -> dict:
+    """
+    Squad of a club for a season (current squad when `season_id` is omitted).
+
+    Player details come from today's player records. `signedFrom` (and `joinedOn` for past seasons) come from the
+    latest transfer into this club up to that season. For a past season, other time-dependent fields (age, contract,
+    market value) are null rather than today's values, and `currentClub` names where the player is now.
+    Every squad member is returned, even if its player record is missing upstream.
+    """
+    squad, reference = await gather(tfmkt.club_squad(club_id, season_id), get_reference(tfmkt))
+    members = squad.get("squad") or []
+    player_ids = [str(m["playerId"]) for m in members]
+    is_current = all(m.get("type") == "current" for m in members)
+
+    players, histories = await gather(
+        tfmkt.players(player_ids),
+        gather(*(tfmkt.player_transfer_history(i) for i in player_ids)),
+    )
+    max_season = int(season_id) if season_id and not is_current else None
+    arrivals = {i: latest_arrival(history, club_id, max_season) for i, history in zip(player_ids, histories)}
+    assignments = {i: current_assignment(players.get(i, {})) for i in player_ids}
+    squad_members = {str(member["playerId"]): member for member in members}
+    clubs = await tfmkt.clubs(
+        [a["transferSource"]["clubId"] for a in arrivals.values() if a]
+        + ([] if is_current else [a["clubId"] for a in assignments.values() if a]),
+    )
+
+    result = []
+    for player_id in player_ids:
+        player = players.get(player_id, {})
+        attributes = player.get("attributes") or {}
+        assignment = assignments[player_id]
+        arrival = arrivals[player_id]
+        entry = {
+            "id": player_id,
+            "name": player.get("name"),
+            "imageUrl": player.get("portraitUrl"),
+            "shirtNumber": squad_members[player_id].get("shirtNumber"),
+            "isCaptain": squad_members[player_id].get("isCaptain"),
+            "position": (attributes.get("position") or {}).get("name"),
+            "dateOfBirth": date_of_birth(player),
+            "nationality": reference.country_names(*nationality_ids(player)),
+            "height": height_cm(player),
+            "foot": (attributes.get("preferredFoot") or {}).get("name"),
+            "signedFrom": clubs.get(str(arrival["transferSource"]["clubId"]), {}).get("name") if arrival else None,
+        }
+        if is_current:
+            in_this_club = assignment is not None and str(assignment.get("clubId")) == str(club_id)
+            entry |= {
+                "age": (player.get("lifeDates") or {}).get("age"),
+                "joinedOn": assignment.get("start") if assignment is not None and in_this_club else None,
+                "contract": attributes.get("contractUntil"),
+                "marketValue": market_value_of((player.get("marketValueDetails") or {}).get("current")),
+            }
+        else:
+            entry |= {
+                "joinedOn": (arrival["details"].get("date") or "")[:10] or None if arrival else None,
+                "currentClub": clubs.get(str(assignment["clubId"]), {}).get("name") if assignment else None,
+            }
+        result.append(entry)
+
+    return {"id": club_id, "players": result}
+
+
+def latest_arrival(history: Optional[dict], club_id: str, max_season: Optional[int]) -> Optional[dict]:
+    """The most recent completed transfer into `club_id`, optionally limited to seasons up to `max_season`."""
+    records = ((history or {}).get("history") or {}).get("terminated") or []
+    arrivals = [
+        record
+        for record in records
+        if str(record["transferDestination"]["clubId"]) == str(club_id)
+        and (max_season is None or (record["details"].get("seasonId") or 0) <= max_season)
+    ]
+    return max(arrivals, key=lambda record: record["details"].get("date") or "", default=None)