transfermarkt-api 5.0.0__py3-none-any.whl

transfermarkt_api/services/clubs/profile.py

@@ -0,0 +1,114 @@
+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
+
+
+async def get_club_profile(tfmkt: TfmktClient, club_id: str) -> dict:
+    """
+    Club profile.
+
+    `officialName`, the address and the colors come from the club's superior (parent) club record. For national
+    teams that record is the football association, so `officialName` is omitted for them.
+    """
+    club, squad, stadium, club_coach, reference = await gather(
+        tfmkt.club(club_id),
+        tfmkt.club_squad(club_id),
+        tfmkt.club_stadium(club_id),
+        tfmkt.club_coach(club_id),
+        get_reference(tfmkt),
+    )
+    coach_id = str(club_coach["coachId"]) if club_coach and club_coach.get("coachId") else None
+    coaches = await tfmkt.coaches([coach_id]) if coach_id else {}
+    base = club.get("baseDetails") or {}
+    superior = base.get("superiorClub") or {}
+    location = superior.get("location") or {}
+    squad_details = club.get("squadDetails") or {}
+    competition_id = base.get("primaryCompetitionId") or None
+    competition = (await tfmkt.competitions([competition_id])).get(competition_id, {}) if competition_id else {}
+    competition_origin = competition.get("originDetails") or {}
+    country = reference.country(base.get("countryId"))
+    stadium_location = (stadium or {}).get("location") or {}
+    building = (stadium or {}).get("buildingDetails") or {}
+    postcode_city = " ".join(part for part in (location.get("postcode"), location.get("city")) if part)
+
+    return {
+        "id": club_id,
+        "url": club.get("relativeUrl"),
+        "name": club.get("name"),
+        "shortName": base.get("shortName") or None,
+        "abbreviation": base.get("abbreviation") or None,
+        "clubCode": (club.get("preferences") or {}).get("clubCode") or None,
+        "officialName": None if base.get("isNationalTeam") else superior.get("name") or None,
+        "image": club.get("crestUrl"),
+        "addressLine1": (location.get("street") or "").strip() or None,
+        "addressLine2": postcode_city or None,
+        "addressLine3": reference.country_name(location.get("countryId")),
+        "colors": [color for color in (superior.get("colors") or {}).values() if color],
+        "stadiumName": (stadium or {}).get("name"),
+        "stadiumSeats": (stadium or {}).get("capacity"),
+        "stadium": {
+            "id": str(stadium["id"]) if stadium.get("id") is not None else None,
+            "name": stadium.get("name") or None,
+            "capacity": stadium.get("capacity"),
+            "internationalCapacity": stadium.get("internationalCapacity"),
+            "website": stadium.get("url") or None,
+            "addressLine1": (stadium_location.get("street") or "").strip() or None,
+            "addressLine2": " ".join(
+                part for part in (stadium_location.get("postcode"), stadium_location.get("city")) if part
+            )
+            or None,
+            "countryId": str(stadium_location["countryId"]) if stadium_location.get("countryId") is not None else None,
+            "countryName": reference.country_name(stadium_location.get("countryId")),
+            "latitude": stadium_location.get("latitude"),
+            "longitude": stadium_location.get("longitude"),
+            "buildYear": building.get("buildYear") or None,
+            "renovationYear": building.get("renovationYear") or None,
+            "fieldLength": building.get("fieldLength") or None,
+            "fieldWidth": building.get("fieldWidth") or None,
+            "fieldSurface": building.get("fieldSurface") or None,
+            "images": list(dict.fromkeys(image["url"] for image in stadium.get("images") or [] if image.get("url"))),
+        }
+        if stadium
+        else None,
+        "currentMarketValue": market_value_of(squad_details.get("currentMarketValue")),
+        "confederation": (
+            reference.confederation_name(country.get("confederationId")) if base.get("isNationalTeam") else None
+        ),
+        "coach": {
+            "id": coach_id,
+            "name": coaches.get(coach_id, {}).get("name"),
+            "since": (club_coach.get("startDate") or "")[:10] or None,
+        }
+        if coach_id
+        else None,
+        "squad": {
+            "size": squad_details.get("squadSize"),
+            "averageAge": float(squad_details["averageAgeDisplay"]) if squad_details.get("averageAgeDisplay") else None,
+            "foreigners": squad.get("foreignCount"),
+            "nationalTeamPlayers": squad.get("nationalCount"),
+            "domesticPlayers": squad.get("localCount"),
+            "averageMarketValue": market_value_of(squad_details.get("averageMarketValue")),
+            "acquisitionValue": value_of(squad_details.get("acquisitionValue")),
+            "top18PlayersMarketValue": market_value_of(squad_details.get("top18PlayersMarketValue")),
+            "top18SharePercentage": (squad_details.get("top18SharePercentage") or {}).get("value"),
+        },
+        "league": {
+            "id": competition_id,
+            "name": competition.get("name"),
+            "countryId": str(competition_origin["countryId"]) if competition_origin.get("countryId") else None,
+            "countryName": reference.country_name(competition_origin.get("countryId")),
+            "tier": reference.competition_type_name(competition.get("typeId")),
+        },
+        "historicalNames": [
+            {
+                "name": entry.get("name") or None,
+                "shortName": entry.get("shortName") or None,
+                "abbreviation": entry.get("abbreviation") or None,
+                "seasonId": str(entry["seasonId"]) if entry.get("seasonId") is not None else None,
+            }
+            for entry in (club.get("historical") or {}).get("names") or []
+        ],
+        "historicalCrests": list(
+            dict.fromkeys(image["url"] for image in (club.get("historical") or {}).get("images") or [])
+        ),
+    }

transfermarkt_api/services/clubs/search.py

@@ -0,0 +1,33 @@
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import get_reference, last_page_number, market_value_of
+
+
+async def search_clubs(tfmkt: TfmktClient, query: str, page_number: int) -> dict:
+    """Search clubs by name. Results keep the upstream search ranking."""
+    search = await tfmkt.quick_search(query, page_number)
+    club_ids = [str(i) for i in search["result"]["clubIds"]]
+
+    clubs, reference = await gather(tfmkt.clubs(club_ids), get_reference(tfmkt))
+
+    results = []
+    for club_id in club_ids:
+        club = clubs.get(club_id, {})
+        squad = club.get("squadDetails") or {}
+        results.append(
+            {
+                "id": club_id,
+                "url": club.get("relativeUrl"),
+                "name": club.get("name"),
+                "country": reference.country_name((club.get("baseDetails") or {}).get("countryId")),
+                "squad": squad.get("squadSize"),
+                "marketValue": market_value_of(squad.get("currentMarketValue")),
+            },
+        )
+
+    return {
+        "query": query,
+        "pageNumber": page_number,
+        "lastPageNumber": last_page_number(search["totalCount"]["clubs"]),
+        "results": results,
+    }

transfermarkt_api/services/coaches/profile.py

@@ -0,0 +1,29 @@
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import Reference, date_of_birth, full_url, get_reference, nationality_ids
+
+
+def coach_summary(coach: dict, reference: Reference) -> dict:
+    """Map an upstream coach record to the public coach fields."""
+    birth = coach.get("birthPlaceDetails") or {}
+    return {
+        "id": str(coach["id"]),
+        "url": full_url(coach.get("relativeUrl")),
+        "name": coach.get("name"),
+        "nameInHomeCountry": (coach.get("nationalityDetails") or {}).get("passportName") or None,
+        "imageUrl": coach.get("portraitUrl"),
+        "dateOfBirth": date_of_birth(coach),
+        "age": (coach.get("lifeDates") or {}).get("age"),
+        "placeOfBirth": {
+            "city": birth.get("placeOfBirth") or None,
+            "country": reference.country_name(birth.get("countryOfBirthId")),
+        },
+        "citizenship": reference.country_names(*nationality_ids(coach)),
+        "license": ((coach.get("attributes") or {}).get("license") or {}).get("name"),
+    }
+
+
+async def get_coach_profile(tfmkt: TfmktClient, coach_id: str) -> dict:
+    """Coach profile. The upstream record has no current club; use a club profile's `coach` for that."""
+    coach, reference = await gather(tfmkt.coach(coach_id), get_reference(tfmkt))
+    return coach_summary(coach, reference)

transfermarkt_api/services/coaches/search.py

@@ -0,0 +1,18 @@
+from transfermarkt_api.services.coaches.profile import coach_summary
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import get_reference, last_page_number
+
+
+async def search_coaches(tfmkt: TfmktClient, query: str, page_number: int) -> dict:
+    """Search coaches by name. Results keep the upstream search ranking."""
+    search = await tfmkt.quick_search(query, page_number)
+    coach_ids = [str(i) for i in search["result"]["coachIds"]]
+    coaches, reference = await gather(tfmkt.coaches(coach_ids), get_reference(tfmkt))
+
+    return {
+        "query": query,
+        "pageNumber": page_number,
+        "lastPageNumber": last_page_number(search["totalCount"]["coaches"]),
+        "results": [coach_summary(coaches.get(i, {"id": i}), reference) for i in coach_ids],
+    }

transfermarkt_api/services/competitions/clubs.py

@@ -0,0 +1,30 @@
+from typing import Optional
+
+from transfermarkt_api.exceptions import NotFound
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+
+
+async def get_competition_clubs(tfmkt: TfmktClient, competition_id: str, season_id: Optional[str] = None) -> dict:
+    """
+    List the clubs that took part in a competition season (current season when `season_id` is omitted).
+
+    Club names are the clubs' current names; the membership itself is historical.
+    """
+    membership, competitions = await gather(
+        tfmkt.competition_clubs(competition_id, season_id),
+        tfmkt.competitions([competition_id]),
+    )
+    competition = competitions.get(competition_id)
+    if competition is None:
+        raise NotFound(f"Competition not found: {competition_id}")
+
+    club_ids = [str(i) for i in membership["clubIds"]]
+    clubs = await tfmkt.clubs(club_ids)
+
+    return {
+        "id": competition_id,
+        "name": competition["name"],
+        "seasonId": str(membership["seasonId"]),
+        "clubs": [{"id": club_id, "name": clubs.get(club_id, {}).get("name")} for club_id in club_ids],
+    }

transfermarkt_api/services/competitions/search.py

@@ -0,0 +1,61 @@
+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, value_of
+
+
+async def search_competitions(tfmkt: TfmktClient, query: str, page_number: int) -> dict:
+    """
+    Search competitions by name.
+
+    `clubs` and `players` count the current season's member clubs and the sum of their squad sizes, and
+    `meanMarketValue` is the total market value divided by the number of clubs. This reproduces the website's
+    figures (e.g. Premier League 2026: 20 clubs, 542 players).
+    """
+    search = await tfmkt.quick_search(query, page_number)
+    competition_ids = [str(i) for i in search["result"]["competitionIds"]]
+
+    competitions, reference, memberships = await gather(
+        tfmkt.competitions(competition_ids),
+        get_reference(tfmkt),
+        # some competitions (e.g. finished tournaments) may have no current membership
+        gather(*(tfmkt.get_optional(f"/competition/{i}/club") for i in competition_ids)),
+    )
+    club_ids_by_competition = {
+        i: [str(c) for c in m["clubIds"]] if m else None for i, m in zip(competition_ids, memberships)
+    }
+    clubs = await tfmkt.clubs(c for ids in club_ids_by_competition.values() for c in ids or [])
+
+    results = []
+    for competition_id in competition_ids:
+        competition = competitions.get(competition_id, {})
+        club_ids = club_ids_by_competition[competition_id]
+        total_market_value = value_of(competition.get("totalMarketValue"))
+        origin = competition.get("originDetails") or {}
+        results.append(
+            {
+                "id": competition_id,
+                "name": competition.get("name"),
+                "country": reference.country_name(origin.get("countryId")),
+                "clubs": len(club_ids) if club_ids is not None else None,
+                "players": squad_total(clubs, club_ids),
+                "totalMarketValue": total_market_value,
+                "meanMarketValue": total_market_value // len(club_ids) if total_market_value and club_ids else None,
+                "continent": reference.confederation_name(origin.get("confederationId")),
+            },
+        )
+
+    return {
+        "query": query,
+        "pageNumber": page_number,
+        "lastPageNumber": last_page_number(search["totalCount"]["competitions"]),
+        "results": results,
+    }
+
+
+def squad_total(clubs: dict, club_ids: Optional[list[str]]) -> Optional[int]:
+    """Sum the squad sizes of the given clubs; None when the membership is unknown."""
+    if club_ids is None:
+        return None
+    return sum((clubs.get(c, {}).get("squadDetails") or {}).get("squadSize") or 0 for c in club_ids)

transfermarkt_api/services/competitions/seasons.py

@@ -0,0 +1,28 @@
+from transfermarkt_api.exceptions import NotFound
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+
+
+async def get_competition_seasons(tfmkt: TfmktClient, competition_id: str) -> dict:
+    """Seasons available for a competition, most recent first. Use `id` as `season_id` in other endpoints."""
+    data, competitions = await gather(
+        tfmkt.competition_seasons(competition_id),
+        tfmkt.competitions([competition_id]),
+    )
+    competition = competitions.get(competition_id)
+    if competition is None:
+        raise NotFound(f"Competition not found: {competition_id}")
+
+    seasons = sorted(data.get("seasons") or [], key=lambda s: s.get("seasonId") or 0, reverse=True)
+    return {
+        "id": competition_id,
+        "name": competition.get("name"),
+        "seasons": [
+            {
+                "id": str(season["seasonId"]),
+                "name": (season.get("season") or {}).get("display"),
+                "matchDays": season.get("gameDays"),
+            }
+            for season in seasons
+        ],
+    }

transfermarkt_api/services/competitions/table.py

@@ -0,0 +1,61 @@
+from typing import Optional
+
+from transfermarkt_api.exceptions import NotFound
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+
+
+async def get_competition_table(tfmkt: TfmktClient, competition_id: str, season_id: Optional[str] = None) -> dict:
+    """
+    League table for a season (current season when `season_id` is omitted).
+
+    Group-stage competitions return one table per group; knockout-only competitions (cups) return no tables.
+    """
+    data, competitions = await gather(
+        tfmkt.competition_table(competition_id, season_id),
+        tfmkt.competitions([competition_id]),
+    )
+    competition = competitions.get(competition_id)
+    if competition is None:
+        raise NotFound(f"Competition not found: {competition_id}")
+
+    tables = data.get("tables") or []
+    clubs = await tfmkt.clubs(row["clubId"] for table in tables for row in table.get("clubs") or [])
+    # upstream `meta.seasonId` always names the current season, even when an older season was requested
+    resolved_season = season_id or str(((data.get("meta") or {}).get("seasonId")) or competition.get("currentSeasonId"))
+
+    return {
+        "id": competition_id,
+        "name": competition.get("name"),
+        "seasonId": resolved_season,
+        "tables": [
+            {
+                "name": (table.get("meta") or {}).get("name"),
+                "rows": [table_row(row, clubs) for row in table.get("clubs") or []],
+            }
+            for table in tables
+        ],
+    }
+
+
+def table_row(row: dict, clubs: dict) -> dict:
+    """Map an upstream table row to the public table row fields."""
+    games = row.get("game") or {}
+    goals = row.get("goal") or {}
+    ranking = row.get("ranking") or {}
+    club_id = str(row["clubId"])
+    return {
+        "position": ranking.get("current"),
+        "previousPosition": ranking.get("previous"),
+        "clubId": club_id,
+        "clubName": clubs.get(club_id, {}).get("name"),
+        "matches": games.get("totalCount"),
+        "wins": games.get("winCount"),
+        "draws": games.get("drawCount"),
+        "losses": games.get("lossCount"),
+        "goalsFor": goals.get("totalCount"),
+        "goalsAgainst": goals.get("concededCount"),
+        "goalDifference": goals.get("differenceCount"),
+        "points": games.get("points"),
+        "zone": (row.get("positioning") or {}).get("description") or None,
+    }

transfermarkt_api/services/countries.py

@@ -0,0 +1,12 @@
+"""Country reference data assembly shared by SDK and server."""
+
+from transfermarkt_api.exceptions import UpstreamError
+from transfermarkt_api.tfmkt import TfmktClient
+
+
+async def list_countries(tfmkt: TfmktClient) -> dict:
+    """List upstream country metadata, including historical entries."""
+    countries = (await tfmkt.attributes()).get("countries")
+    if not isinstance(countries, list) or not all(isinstance(country, dict) for country in countries):
+        raise UpstreamError("Unexpected upstream payload for /attributes countries")
+    return {"countries": countries}

transfermarkt_api/services/games/game.py

@@ -0,0 +1,136 @@
+import asyncio
+from typing import Optional, cast
+
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.reference import full_url
+
+EVENT_TYPES = {"GOAL": "goal", "CARD": "card", "SUBSTITUTE": "substitution"}
+# team stat -> (clubStatistics group, upstream field)
+TEAM_STATS = {
+    "possession": ("gameStatistics", "possessionPercentage"),
+    "shots": ("goalStatistics", "totalShotAttempts"),
+    "shotsOnTarget": ("goalStatistics", "onTargetShotAttempts"),
+    "shotsOffTarget": ("goalStatistics", "offTargetShotAttempts"),
+    "shotsBlocked": ("goalStatistics", "blockedShotAttempts"),
+    "passes": ("passingStatistics", "totalPasses"),
+    "accuratePasses": ("passingStatistics", "accuratePasses"),
+    "tackles": ("defensiveStatistics", "totalTackles"),
+    "tacklesWon": ("defensiveStatistics", "successfulTackles"),
+    "clearances": ("defensiveStatistics", "clearances"),
+    "saves": ("defensiveStatistics", "saves"),
+    "offsides": ("defensiveStatistics", "offsides"),
+    "corners": ("setPieceStatistics", "cornersTaken"),
+    "foulsCommitted": ("penaltyStatistics", "freeKicksConcededFromFouls"),
+    "foulsSuffered": ("penaltyStatistics", "freeKicksWonFromFouls"),
+    "yellowCards": ("gameStatistics", "yellowCards"),
+    "secondYellowCards": ("gameStatistics", "secondYellowCards"),
+    "redCards": ("gameStatistics", "redCards"),
+    "penaltiesWon": ("penaltyStatistics", "penaltiesWon"),
+    "penaltiesSaved": ("penaltyStatistics", "penaltiesSaved"),
+    "ownGoals": ("penaltyStatistics", "ownGoals"),
+}
+
+
+async def get_game(tfmkt: TfmktClient, game_id: str) -> dict:
+    """
+    A match with both lineups, coaches, score and events.
+
+    `stats` holds team statistics (possession, shots, passes, ...) when upstream recorded them, mostly for recent
+    matches in major competitions; otherwise it is null. Events are goals, cards and substitutions in match order.
+    For a goal, `relatedPlayer` is the assist; for a substitution, `player` goes off and `relatedPlayer` comes on.
+    """
+    game = await tfmkt.game(game_id)
+    base = game.get("baseDetails") or {}
+    sides = {"home": game.get("homeClub") or {}, "away": game.get("awayClub") or {}}
+    actions = [action for action in game.get("actions") or [] if action.get("type") in EVENT_TYPES]
+    lineups = {
+        name: {group: (side.get("lineup") or {}).get(group) or [] for group in ("players", "substitutes")}
+        for name, side in sides.items()
+    }
+    player_ids = [p["id"] for lineup in lineups.values() for group in lineup.values() for p in group] + [
+        action[key] for action in actions for key in ("activePlayerId", "passivePlayerId") if action.get(key)
+    ]
+    stadium_id = base.get("stadiumId")
+
+    players, clubs, coaches, stadium = await gather(
+        tfmkt.players(player_ids),
+        tfmkt.clubs(side.get("clubId") for side in sides.values()),
+        tfmkt.coaches(side.get("coachId") for side in sides.values()),
+        tfmkt.stadium(stadium_id) if stadium_id else asyncio.sleep(0),
+    )
+
+    def entity(entity_id: Optional[str], records: dict) -> Optional[dict]:
+        """`{id, name}` for a referenced player, club or coach, or None when there is no ID."""
+        if not entity_id:
+            return None
+        return {"id": str(entity_id), "name": records.get(str(entity_id), {}).get("name")}
+
+    def lineup_player(player: dict) -> dict:
+        """A lineup entry with the player's name."""
+        return {
+            **cast(dict, entity(player["id"], players)),
+            "shirtNumber": player.get("shirtNumber"),
+            "position": (player.get("position") or {}).get("name"),
+            "isCaptain": bool(player.get("isCaptain")),
+        }
+
+    score = game.get("score") or {}
+    competition = base.get("competition") or {}
+    date = base.get("date") or {}
+
+    return {
+        "id": str(game.get("id") or game_id),
+        "url": full_url(game.get("relativeUrl")),
+        "competition": {"id": base.get("competitionId"), "name": competition.get("name")},
+        "seasonId": str(base["seasonId"]) if base.get("seasonId") is not None else None,
+        "season": (base.get("season") or {}).get("display"),
+        "matchDay": base.get("gameDay") or None,
+        "date": date.get("dateTimeUTC"),
+        "stadium": {"id": str(stadium_id), "name": (stadium or {}).get("name")} if stadium_id else None,
+        "attendance": (game.get("extendedDetails") or {}).get("crowdSize") or None,
+        **{
+            name: {
+                **cast(dict, entity(side.get("clubId"), clubs)),
+                "score": score.get(name),
+                "formation": (side.get("tactic") or {}).get("tactic"),
+                "coach": entity(side.get("coachId"), coaches),
+                "stats": team_stats(side.get("clubStatistics")),
+                "startingLineup": [lineup_player(p) for p in lineups[name]["players"]],
+                "substitutes": [lineup_player(p) for p in lineups[name]["substitutes"]],
+            }
+            for name, side in sides.items()
+        },
+        "events": [
+            {
+                "type": EVENT_TYPES[action["type"]],
+                "minute": action.get("minute"),
+                "addedTime": action.get("addedTime") or None,
+                "clubId": str(action["clubId"]) if action.get("clubId") else None,
+                "player": entity(action.get("activePlayerId"), players),
+                "relatedPlayer": entity(action.get("passivePlayerId"), players),
+                "card": card_type(action) if action["type"] == "CARD" else None,
+                "score": action.get("score") if action["type"] == "GOAL" else None,
+            }
+            for action in sorted(actions, key=lambda a: (a.get("minute") or 0, a.get("addedTime") or 0))
+        ],
+    }
+
+
+def card_type(action: dict) -> Optional[str]:
+    """Card colour, read from the season counter upstream increments (`seasonYellowCard`, `seasonRedCard`, ...)."""
+    keys = " ".join((action.get("details") or {}).keys())
+    if "YellowRed" in keys:
+        return "secondYellow"
+    if "Red" in keys:
+        return "red"
+    if "Yellow" in keys:
+        return "yellow"
+    return None
+
+
+def team_stats(statistics: Optional[dict]) -> Optional[dict]:
+    """A side's match statistics, or None when upstream has none for the match."""
+    if not statistics:
+        return None
+    return {name: (statistics.get(group) or {}).get(field) for name, (group, field) in TEAM_STATS.items()}

transfermarkt_api/services/players/absences.py

@@ -0,0 +1,33 @@
+from transfermarkt_api.services.players.injuries import PAGE_SIZE, inclusive_days
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.reference import last_page_number, season_label
+
+
+async def get_player_absences(tfmkt: TfmktClient, player_id: str, page_number: int) -> dict:
+    """
+    Non-injury absences (suspensions, national-team call-ups, leave), most recent first, paginated like injuries.
+
+    `days` counts both the first and last day, as for injuries.
+    """
+    absences = (await tfmkt.player_absences(player_id)).get("absences") or []
+    page = absences[(page_number - 1) * PAGE_SIZE : page_number * PAGE_SIZE]
+    competitions = await tfmkt.competitions(a.get("competitionId") for a in page if a.get("competitionId"))
+
+    return {
+        "id": player_id,
+        "pageNumber": page_number,
+        "lastPageNumber": last_page_number(len(absences), PAGE_SIZE),
+        "absences": [
+            {
+                "season": season_label(absence.get("seasonId")),
+                "reason": absence.get("name"),
+                "competitionId": absence.get("competitionId") or None,
+                "competitionName": competitions.get(absence.get("competitionId") or "", {}).get("name"),
+                "fromDate": absence.get("start"),
+                "untilDate": absence.get("end"),
+                "days": inclusive_days(absence),
+                "gamesMissed": absence.get("missedGamesCount"),
+            }
+            for absence in page
+        ],
+    }

transfermarkt_api/services/players/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_player_achievements(tfmkt: TfmktClient, player_id: str) -> dict:
+    """Titles and individual awards, including participations, runner-up and third places."""
+    # the achievement route answers 200 with no data for unknown players; the player lookup gives a proper 404
+    _, data = await gather(tfmkt.player(player_id), tfmkt.player_achievements(player_id))
+    return {"id": player_id, "achievements": await group_achievements(tfmkt, data)}

transfermarkt_api/services/players/injuries.py

@@ -0,0 +1,42 @@
+from datetime import date
+from typing import Optional
+
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.reference import last_page_number, season_label
+
+PAGE_SIZE = 15  # the website's injury history page size, kept for pagination compatibility
+
+
+async def get_player_injuries(tfmkt: TfmktClient, player_id: str, page_number: int) -> dict:
+    """
+    Injury history, most recent first, paginated locally.
+
+    `days` counts both the first and last day, as the website does (upstream `durationDetails.days` is one less).
+    """
+    injuries = (await tfmkt.player_injuries(player_id)).get("injuries") or []
+    page = injuries[(page_number - 1) * PAGE_SIZE : page_number * PAGE_SIZE]
+
+    return {
+        "id": player_id,
+        "pageNumber": page_number,
+        "lastPageNumber": last_page_number(len(injuries), PAGE_SIZE),
+        "injuries": [
+            {
+                "season": season_label(injury.get("seasonId")),
+                "injury": injury.get("name"),
+                "fromDate": injury.get("start"),
+                "untilDate": injury.get("end"),
+                "days": inclusive_days(injury),
+                "gamesMissed": injury.get("missedGamesCount"),
+            }
+            for injury in page
+        ],
+    }
+
+
+def inclusive_days(injury: dict) -> Optional[int]:
+    """Injury length in days, counting both the first and the last day."""
+    if injury.get("start") and injury.get("end"):
+        return (date.fromisoformat(injury["end"]) - date.fromisoformat(injury["start"])).days + 1
+    days = (injury.get("durationDetails") or {}).get("days")
+    return days + 1 if days is not None else None