transfermarkt-api 5.0.0__py3-none-any.whl

transfermarkt_api/services/players/market_value.py

@@ -0,0 +1,35 @@
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import market_value_of
+
+
+async def get_player_market_value(tfmkt: TfmktClient, player_id: str) -> dict:
+    """
+    Current market value, valuation history (oldest first) and worldwide market-value ranking.
+
+    Club names are the clubs' current names. Only the worldwide ranking is available upstream; the v3 position,
+    club and country rankings have no JSON source.
+    """
+    data, ranking = await gather(
+        tfmkt.player_market_value_history(player_id),
+        tfmkt.player_market_value_ranking(player_id),
+    )
+    history = sorted(data.get("history") or [], key=lambda e: (e.get("marketValue") or {}).get("determined") or "")
+    clubs = await tfmkt.clubs(entry.get("clubId") for entry in history)
+    worldwide = (ranking or {}).get("ranking")
+
+    return {
+        "id": player_id,
+        "marketValue": market_value_of((data.get("current") or {}).get("marketValue")),
+        "marketValueHistory": [
+            {
+                "age": entry.get("age"),
+                "date": (entry.get("marketValue") or {}).get("determined"),
+                "clubId": str(entry["clubId"]) if entry.get("clubId") else None,
+                "clubName": clubs.get(str(entry.get("clubId")), {}).get("name"),
+                "marketValue": market_value_of(entry.get("marketValue")),
+            }
+            for entry in history
+        ],
+        "ranking": {"Worldwide": worldwide} if worldwide else None,
+    }

transfermarkt_api/services/players/matches.py

@@ -0,0 +1,107 @@
+from typing import Optional
+
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import get_reference, last_page_number
+
+PAGE_SIZE = 50
+# upstream participationState -> participation; other values are passed through unchanged
+PARTICIPATION = {
+    "played": "played",
+    "in squad": "onBench",
+    "not in squad": "notInSquad",
+    "injured": "injured",
+    "absent": "absent",
+}
+# detailed stat -> (statistics group, upstream field); null when upstream did not record it for the match
+DETAILED_STATS = {
+    "ownGoals": ("goalStatistics", "ownGoalsScored"),
+    "penaltyGoals": ("goalStatistics", "penaltyShooterGoalsScored"),
+    "penaltiesMissed": ("goalStatistics", "penaltyShooterMisses"),
+    "penaltiesSaved": ("goalStatistics", "penaltyGoalkeeperSaves"),
+    "shots": ("goalStatistics", "scoringAttempts"),
+    "shotsOnTarget": ("goalStatistics", "scoringAttemptsOnGoal"),
+    "passes": ("distributionStatistics", "passes"),
+    "accuratePasses": ("distributionStatistics", "passesReached"),
+    "tackles": ("duelStatistics", "tackles"),
+    "tacklesWon": ("duelStatistics", "tacklesWon"),
+    "foulsCommitted": ("duelStatistics", "foulsCommitted"),
+    "foulsSuffered": ("duelStatistics", "foulsGained"),
+    "offsides": ("duelStatistics", "offsides"),
+}
+
+
+async def get_player_matches(
+    tfmkt: TfmktClient,
+    player_id: str,
+    page_number: int,
+    season_id: Optional[str] = None,
+) -> dict:
+    """
+    Matches of the player's teams, most recent first, paginated, with the player's part in each.
+
+    Includes matches the player missed (`participation` tells why) and national-team matches. Detailed statistics
+    (shots, passes, tackles, ...) are null when upstream did not record them, which is common before 2018. Only past
+    matches are available upstream; there is no fixture list.
+    """
+    performance = (await tfmkt.player_performance_games(player_id))["performance"]
+    games = [
+        game
+        for game in performance
+        if season_id is None or str(game["gameInformation"].get("seasonId")) == str(season_id)
+    ]
+    games.sort(key=lambda game: (game["gameInformation"].get("date") or {}).get("dateTimeUTC") or "", reverse=True)
+    page = games[(page_number - 1) * PAGE_SIZE : page_number * PAGE_SIZE]
+
+    competitions, clubs, reference = await gather(
+        tfmkt.competitions(game["gameInformation"]["competitionId"] for game in page),
+        tfmkt.clubs(game["clubsInformation"][side]["clubId"] for game in page for side in ("club", "opponent")),
+        get_reference(tfmkt),
+    )
+
+    def entity(entity_id: str, records: dict) -> dict:
+        """`{id, name}` for a referenced club or competition."""
+        return {"id": str(entity_id), "name": records.get(str(entity_id), {}).get("name")}
+
+    matches = []
+    for game in page:
+        info, teams, stats = game["gameInformation"], game["clubsInformation"], game["statistics"]
+        general = stats["generalStatistics"]
+        state = general.get("participationState")
+        cards = stats.get("cardStatistics") or {}
+        goals = stats.get("goalStatistics") or {}
+        playing_time = stats.get("playingTimeStatistics") or {}
+        matches.append({
+            "gameId": str(info["gameId"]),
+            "date": (info.get("date") or {}).get("dateTimeUTC"),
+            "season": (info.get("season") or {}).get("display"),
+            "competition": entity(info["competitionId"], competitions),
+            "matchDay": info.get("gameDay") or None,
+            "club": entity(teams["club"]["clubId"], clubs),
+            "opponent": entity(teams["opponent"]["clubId"], clubs),
+            "venue": teams["club"].get("venue"),
+            "clubGoals": teams["club"].get("goalsTotal"),
+            "opponentGoals": teams["opponent"].get("goalsTotal"),
+            "participation": PARTICIPATION.get(state, state),
+            "shirtNumber": general.get("shirtNumber"),
+            "isCaptain": bool(general.get("isCaptain")),
+            "position": reference.position_name(general.get("positionId")),
+            "isStarting": bool(playing_time.get("isStarting")),
+            "substitutedInMinute": (playing_time.get("substitutedIn") or {}).get("minute"),
+            "substitutedOutMinute": (playing_time.get("substitutedOut") or {}).get("minute"),
+            "minutesPlayed": playing_time.get("playedMinutes") or 0,
+            "teamPoints": teams["club"].get("points"),
+            "goals": goals.get("goalsScoredTotal") or 0,
+            "assists": goals.get("assists") or 0,
+            "yellowCard": bool(cards.get("yellowCard")),
+            "secondYellowCard": bool(cards.get("yellowRedCard")),
+            "redCard": bool(cards.get("redCard")),
+            **{name: (stats.get(group) or {}).get(field) for name, (group, field) in DETAILED_STATS.items()},
+        })
+
+    return {
+        "id": player_id,
+        "pageNumber": page_number,
+        "lastPageNumber": last_page_number(len(games), PAGE_SIZE),
+        "matches": matches,
+    }

transfermarkt_api/services/players/national_career.py

@@ -0,0 +1,31 @@
+from transfermarkt_api.tfmkt import TfmktClient
+
+CAREER_STATUS = {
+    "CURRENT_NATIONAL_PLAYER": "current",
+    "RECENT_NATIONAL_PLAYER": "recent",
+    "FORMER_NATIONAL_PLAYER": "former",
+}
+
+
+async def get_player_national_career(tfmkt: TfmktClient, player_id: str) -> dict:
+    """Senior and youth national teams the player has played for, in upstream order (most recent team first)."""
+    history = (await tfmkt.player_national_career(player_id)).get("history") or []
+    clubs = await tfmkt.clubs(entry.get("clubId") for entry in history)
+
+    return {
+        "id": player_id,
+        "nationalTeams": [
+            {
+                "id": str(entry["clubId"]),
+                "name": clubs.get(str(entry["clubId"]), {}).get("name"),
+                "appearances": entry.get("gamesPlayed"),
+                "goals": entry.get("goalsScored"),
+                "shirtNumber": entry.get("shirtNumber"),
+                "isCaptain": entry.get("isCaptain"),
+                "debut": entry.get("debut"),
+                "lastMatch": entry.get("lastGame"),
+                "status": CAREER_STATUS.get(entry.get("careerState")),
+            }
+            for entry in history
+        ],
+    }

transfermarkt_api/services/players/profile.py

@@ -0,0 +1,122 @@
+from datetime import date
+from typing import Optional
+
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import (
+    RETIRED_CLUB_ID,
+    current_assignment,
+    date_of_birth,
+    full_url,
+    get_reference,
+    height_cm,
+    market_value_of,
+    nationality_ids,
+)
+
+
+async def get_player_profile(tfmkt: TfmktClient, player_id: str) -> dict:
+    """
+    Player profile.
+
+    A player is retired when assigned to Transfermarkt's special "Retired" club (ID 123); `retiredSince` is the start
+    of that assignment and `club.lastClubId` names the club before it.
+    """
+    player, reference = await gather(tfmkt.player(player_id), get_reference(tfmkt))
+    attributes = player.get("attributes") or {}
+    birth = player.get("birthPlaceDetails") or {}
+    assignment = current_assignment(player) or {}
+    club_id = str(assignment["clubId"]) if assignment.get("clubId") else None
+    is_retired = club_id == RETIRED_CLUB_ID
+    last_club_id = str(player["lastClubId"]) if player.get("lastClubId") else None
+    national = next((a for a in player.get("clubAssignments") or [] if a.get("type") == "nationalTeam"), None)
+    national_id = str(national["clubId"]) if national and national.get("clubId") else None
+
+    clubs = await tfmkt.clubs(i for i in (club_id, last_club_id, national_id) if i)
+    agency = attributes.get("consultantAgency") or {}
+    life = player.get("lifeDates") or {}
+    values = player.get("marketValueDetails") or {}
+    trend = ((values.get("delta") or {}).get("type") or "").lower()
+
+    return {
+        "id": player_id,
+        "url": full_url(player.get("relativeUrl")),
+        "name": player.get("name"),
+        "fullName": player.get("displayName") or None,
+        "nameInHomeCountry": (player.get("nationalityDetails") or {}).get("passportName") or None,
+        "imageUrl": player.get("portraitUrl"),
+        "dateOfBirth": date_of_birth(player),
+        "dateOfDeath": None if life.get("isDateOfDeathUnknown") else life.get("dateOfDeath"),
+        "placeOfBirth": {
+            "city": birth.get("placeOfBirth") or None,
+            "country": reference.country_name(birth.get("countryOfBirthId")),
+        },
+        "age": life.get("age"),
+        "height": height_cm(player),
+        "citizenship": reference.country_names(*nationality_ids(player)),
+        "isRetired": is_retired,
+        "retiredSince": assignment.get("start") if is_retired else None,
+        "position": {
+            "main": (attributes.get("position") or {}).get("name"),
+            "group": attributes.get("positionGroupName"),
+            "other": [
+                position["name"]
+                for position in (attributes.get("firstSidePosition"), attributes.get("secondSidePosition"))
+                if position
+            ],
+        },
+        "foot": (attributes.get("preferredFoot") or {}).get("name"),
+        "shirtNumber": shirt_number_label(assignment.get("shirtNumber")),
+        "club": {
+            "id": club_id,
+            "name": clubs.get(club_id or "", {}).get("name"),
+            "joined": assignment.get("start"),
+            "isCaptain": assignment.get("isCaptain"),
+            "contractExpires": attributes.get("contractUntil"),
+            "lastContractRenewal": date_from_parts(attributes.get("lastContractRenewal")),
+            "contractOption": reference.contract_option_name(attributes.get("contractOptionId")),
+            "lastClubId": last_club_id,
+            "lastClubName": clubs.get(last_club_id or "", {}).get("name"),
+        },
+        "nationalTeam": {
+            "id": national_id,
+            "name": clubs.get(national_id, {}).get("name"),
+            "shirtNumber": shirt_number_label(national.get("shirtNumber")),
+            "isCaptain": national.get("isCaptain"),
+            "debut": national.get("debut"),
+        }
+        if national_id and national
+        else None,
+        "marketValue": market_value_of(values.get("current")),
+        "marketValueDetails": {
+            "lastUpdated": (values.get("current") or {}).get("determined"),
+            "trend": trend if trend in ("increased", "decreased", "unchanged") else None,
+            "previous": dated_value(values.get("previous")),
+            "highest": dated_value(values.get("highest")),
+        }
+        if values
+        else None,
+        "agent": {"name": agency.get("name"), "url": agency.get("relativeUrl")} if agency else None,
+        "outfitter": (attributes.get("outfitter") or {}).get("name"),
+    }
+
+
+def shirt_number_label(number: Optional[int]) -> Optional[str]:
+    """Shirt number as the website shows it, e.g. "#10"."""
+    return f"#{number}" if number is not None else None
+
+
+def dated_value(money: Optional[dict]) -> Optional[dict]:
+    """`{value, date}` for a market value with the date it was set, or None when there is no valuation."""
+    value = market_value_of(money)
+    return {"value": value, "date": money.get("determined")} if value and money else None
+
+
+def date_from_parts(parts: Optional[dict]) -> Optional[str]:
+    """ISO date from upstream `{year, month, day}`, or None when incomplete or invalid."""
+    if parts is None:
+        return None
+    try:
+        return date(parts["year"], parts["month"], parts["day"]).isoformat()
+    except (TypeError, KeyError, ValueError):
+        return None

transfermarkt_api/services/players/search.py

@@ -0,0 +1,44 @@
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import (
+    current_assignment,
+    get_reference,
+    last_page_number,
+    market_value_of,
+    nationality_ids,
+)
+
+
+async def search_players(tfmkt: TfmktClient, query: str, page_number: int) -> dict:
+    """Search players by name. Results keep the upstream search ranking."""
+    search = await tfmkt.quick_search(query, page_number)
+    player_ids = [str(i) for i in search["result"]["playerIds"]]
+
+    players, reference = await gather(tfmkt.players(player_ids), get_reference(tfmkt))
+    assignments = {i: current_assignment(players.get(i, {})) for i in player_ids}
+    clubs = await tfmkt.clubs(a["clubId"] for a in assignments.values() if a)
+
+    results = []
+    for player_id in player_ids:
+        player = players.get(player_id, {})
+        attributes = player.get("attributes") or {}
+        assignment = assignments[player_id]
+        club_id = str(assignment["clubId"]) if assignment else None
+        results.append(
+            {
+                "id": player_id,
+                "name": player.get("name"),
+                "position": (attributes.get("position") or {}).get("shortName"),
+                "club": {"id": club_id, "name": clubs.get(club_id, {}).get("name")} if club_id else None,
+                "age": (player.get("lifeDates") or {}).get("age"),
+                "nationalities": reference.country_names(*nationality_ids(player)),
+                "marketValue": market_value_of((player.get("marketValueDetails") or {}).get("current")),
+            },
+        )
+
+    return {
+        "query": query,
+        "pageNumber": page_number,
+        "lastPageNumber": last_page_number(search["totalCount"]["players"]),
+        "results": results,
+    }

transfermarkt_api/services/players/stats.py

@@ -0,0 +1,74 @@
+from collections import Counter
+
+from transfermarkt_api.tfmkt import TfmktClient
+
+# Competition type IDs the website's detailed stats table leaves out (national-team matches, including friendlies).
+# Mirrors `nationalTeamCompetitions` in the website's player-performance-proxy bundle.
+NATIONAL_TEAM_COMPETITION_TYPE_IDS = {11, 17, 19, 20}
+
+
+async def get_player_stats(tfmkt: TfmktClient, player_id: str) -> dict:
+    """
+    Aggregate a player's match records into per season, competition and club totals.
+
+    Follows the website's own aggregation of `/player/{id}/performance-game`: appearances count matches with
+    participation state `played`, numeric statistics are summed, and each card event counts once. The goalkeeper
+    columns follow the website too: `goalsConceded` sums the opponent goals scored while the player was on the pitch,
+    and `cleanSheets` counts matches the player played in which the opponent did not score at all. Both are computed
+    for every player; the website shows them only for goalkeepers.
+
+    Returns:
+        dict: The player ID and one stats entry per (season, competition, club), most recent season first.
+    """
+    performance = (await tfmkt.player_performance_games(player_id))["performance"]
+    games = [
+        game
+        for game in performance
+        if game["gameInformation"]["competitionTypeId"] not in NATIONAL_TEAM_COMPETITION_TYPE_IDS
+    ]
+
+    totals: dict[tuple[str, str, str], Counter] = {}
+    for game in games:
+        info = game["gameInformation"]
+        key = (str(info["seasonId"]), info["competitionId"], str(game["clubsInformation"]["club"]["clubId"]))
+        total = totals.setdefault(key, Counter())
+        stats = game["statistics"]
+        if stats["generalStatistics"]["participationState"] != "played":
+            continue
+        cards = stats["cardStatistics"]
+        total["appearances"] += 1
+        total["goals"] += stats["goalStatistics"]["goalsScoredTotal"] or 0
+        total["assists"] += stats["goalStatistics"]["assists"] or 0
+        total["yellowCards"] += 1 if cards.get("yellowCard") else 0
+        total["secondYellowCards"] += 1 if cards.get("yellowRedCard") else 0
+        total["redCards"] += 1 if cards.get("redCard") else 0
+        played_minutes = stats["playingTimeStatistics"]["playedMinutes"] or 0
+        total["minutesPlayed"] += played_minutes
+        total["goalsConceded"] += stats["goalStatistics"]["opponentGoalsOnThePitch"] or 0
+        total["cleanSheets"] += (
+            1 if played_minutes and game["clubsInformation"]["club"]["opponentGoalsTotal"] == 0 else 0
+        )
+
+    competitions = await tfmkt.competitions(competition_id for _, competition_id, _ in totals)
+
+    return {
+        "id": player_id,
+        "stats": [
+            {
+                "competitionId": competition_id,
+                "competitionName": competitions.get(competition_id, {}).get("name"),
+                "seasonId": season_id,
+                "clubId": club_id,
+                "appearances": total["appearances"],
+                "goals": total["goals"],
+                "assists": total["assists"],
+                "yellowCards": total["yellowCards"],
+                "secondYellowCards": total["secondYellowCards"],
+                "redCards": total["redCards"],
+                "minutesPlayed": total["minutesPlayed"],
+                "goalsConceded": total["goalsConceded"],
+                "cleanSheets": total["cleanSheets"],
+            }
+            for (season_id, competition_id, club_id), total in totals.items()
+        ],
+    }

transfermarkt_api/services/players/transfers.py

@@ -0,0 +1,89 @@
+import re
+from typing import Optional
+
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import get_reference, market_value_of, value_of
+
+# upstream typeDetails.type -> transferType; STANDARD is split into transfer and freeTransfer by its fee label
+TRANSFER_TYPES = {
+    "STANDARD": "transfer",
+    "INTERNAL_TRANSFER": "internal",
+    "ACTIVE_LOAN_TRANSFER": "loan",
+    "RETURNED_FROM_PREVIOUS_LOAN": "endOfLoan",
+}
+
+# formerClubsNote lists youth clubs as "Grandoli FC (1992-1995), Newell's Old Boys (1995-2000)"
+YOUTH_CLUB_SEPARATOR = re.compile(r"(?<=\)),\s*")
+
+
+async def get_player_transfers(tfmkt: TfmktClient, player_id: str) -> dict:
+    """
+    Transfer history, upcoming (pending) transfers first, then completed ones, most recent first.
+
+    `fee` is null when upstream has no numeric fee: free transfers, loans without fee and unknown fees (`-`).
+    `transferType` tells these apart: an unknown fee is a `transfer` with a null fee, never a `freeTransfer`.
+    """
+    player, history, reference = await gather(
+        tfmkt.player(player_id),
+        tfmkt.player_transfer_history(player_id),
+        get_reference(tfmkt),
+    )
+    transfers = (history or {}).get("history") or {}
+    records = (transfers.get("pending") or []) + (transfers.get("terminated") or [])
+    sides = [side for record in records for side in (record["transferSource"], record["transferDestination"])]
+    clubs, competitions = await gather(
+        tfmkt.clubs(side["clubId"] for side in sides),
+        tfmkt.competitions(side.get("competitionId") for side in sides),
+    )
+
+    def club(side: dict) -> dict:
+        """Club with the league and country recorded at the time of this transfer."""
+        club_id = str(side["clubId"])
+        country_id = side.get("countryId")
+        competition_id = side.get("competitionId")
+        return {
+            "id": club_id,
+            "name": clubs.get(club_id, {}).get("name"),
+            "countryId": str(country_id) if country_id is not None else None,
+            "countryName": reference.country_name(country_id),
+            "league": {
+                "id": str(competition_id),
+                "name": competitions.get(str(competition_id), {}).get("name"),
+            }
+            if competition_id
+            else None,
+        }
+
+    former_clubs_note = (player.get("attributes") or {}).get("formerClubsNote")
+
+    return {
+        "id": player_id,
+        "transfers": [
+            {
+                "id": str(record["id"]),
+                "clubFrom": club(record["transferSource"]),
+                "clubTo": club(record["transferDestination"]),
+                "date": (record["details"].get("date") or "")[:10] or None,
+                "upcoming": bool(record["details"].get("isPending")),
+                "transferType": transfer_type(record),
+                "season": (record["details"].get("season") or {}).get("display"),
+                "marketValue": market_value_of(record["details"].get("marketValue")),
+                "fee": value_of(record["details"].get("fee")),
+                "age": record["details"].get("age"),
+                "contractUntil": (record["details"].get("contractUntilDate") or "")[:10] or None,
+                "remainingContractDays": (record["details"].get("remainingContractPeriod") or {}).get("days"),
+            }
+            for record in records
+        ],
+        "youthClubs": YOUTH_CLUB_SEPARATOR.split(former_clubs_note) if former_clubs_note else [],
+    }
+
+
+def transfer_type(record: dict) -> Optional[str]:
+    """Kind of transfer, or None for an upstream type this API does not know."""
+    kind = TRANSFER_TYPES.get((record.get("typeDetails") or {}).get("type") or "")
+    fee_label = ((record["details"].get("fee") or {}).get("compact") or {}).get("content") or ""
+    if kind == "transfer" and fee_label.strip().lower() == "free transfer":
+        return "freeTransfer"
+    return kind

transfermarkt_api/tfmkt/__init__.py

@@ -0,0 +1 @@
+from transfermarkt_api.tfmkt.client import TfmktClient as TfmktClient