transfermarkt-api 5.0.0__py3-none-any.whl

transfermarkt_api/tfmkt/client.py

@@ -0,0 +1,249 @@
+"""Async client for Transfermarkt's JSON API (tfmkt), the data source of every endpoint migrated off HTML scraping."""
+
+import asyncio
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from typing import Any, Optional
+
+import httpx
+from cachetools import TTLCache
+
+from transfermarkt_api.cache import CacheConfig
+from transfermarkt_api.exceptions import NotFound, UpstreamBlocked, UpstreamError, UpstreamTimeout
+from transfermarkt_api.tfmkt.concurrency import gather
+from transfermarkt_api.tfmkt.freshness import record_fetch
+
+BATCH_SIZE = 100  # batch routes accepted 200 IDs in testing; stay well below
+
+
+class TfmktClient:
+    """
+    Thin wrapper around tfmkt routes.
+
+    Every request goes through `get`, which applies the concurrency cap, the response cache and the upstream error
+    mapping. Successful responses are cached with the time they were fetched, so callers can report data age.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://tmapi.transfermarkt.technology",
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+        *,
+        timeout: float | httpx.Timeout | None = 15.0,
+        max_concurrency: int = 10,
+        cache: CacheConfig | None = CacheConfig(),
+    ) -> None:
+        """Create the HTTP client, concurrency cap and response caches."""
+        url = httpx.URL(base_url)
+        if url.scheme not in ("http", "https") or not url.host or url.query or url.fragment:
+            raise ValueError("base_url must be an absolute HTTP(S) URL without query or fragment")
+        if not isinstance(max_concurrency, int) or isinstance(max_concurrency, bool) or max_concurrency < 1:
+            raise ValueError("max_concurrency must be a positive integer")
+        self._transport_injected = transport is not None
+        self.http = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"Accept": "application/json", "User-Agent": "transfermarkt-api"},
+            timeout=timeout,
+            transport=transport,
+        )
+        self.semaphore = asyncio.Semaphore(max_concurrency)
+        self.cache: TTLCache | None = TTLCache(maxsize=cache.max_entries, ttl=cache.ttl) if cache else None
+        self.reference_cache: TTLCache | None = TTLCache(maxsize=8, ttl=cache.reference_ttl) if cache else None
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client."""
+        await self.http.aclose()
+
+    async def get(self, path: str, params: Optional[list[tuple[str, Any]]] = None, reference: bool = False) -> Any:
+        """
+        Fetch a tfmkt route and return its `data` payload.
+
+        Exceptions from an injected transport propagate unchanged, including httpx errors.
+
+        Raises:
+            TransfermarktError: 404 when upstream does not know the entity, 503 when upstream challenges or rejects the
+                request, 504 on timeout and 502 for any other unexpected upstream response.
+        """
+        if self.http.is_closed:
+            raise RuntimeError("Transfermarkt client is closed")
+        request = self.http.build_request("GET", path, params=params)
+        key = str(request.url)
+        cache = self.reference_cache if reference else self.cache
+        if cache is not None and key in cache:
+            fetched_at, data = cache[key]
+            record_fetch(fetched_at)
+            return data
+
+        async with self.semaphore:
+            try:
+                response = await self.http.send(request)
+            except httpx.TimeoutException as e:
+                if self._transport_injected:
+                    raise
+                raise UpstreamTimeout(f"Upstream timeout for {path}", url=str(request.url)) from e
+            except httpx.HTTPError as e:
+                if self._transport_injected:
+                    raise
+                raise UpstreamError(f"Upstream connection error for {path}: {e}", url=str(request.url)) from e
+
+        data = self._parse(response, path)
+        fetched_at = response.extensions.get("transfermarkt_fetched_at", datetime.now(UTC).replace(tzinfo=None))
+        if not isinstance(fetched_at, datetime):
+            raise UpstreamError("transfermarkt_fetched_at must be a datetime", url=key)
+        if fetched_at.utcoffset() is not None:
+            fetched_at = fetched_at.astimezone(UTC).replace(tzinfo=None)
+        if cache is not None:
+            cache[key] = (fetched_at, data)
+        record_fetch(fetched_at)
+        return data
+
+    async def get_optional(self, path: str, params: Optional[list[tuple[str, Any]]] = None) -> Any:
+        """Like `get`, but returns None when upstream answers 404 (e.g. a club without a stadium)."""
+        try:
+            return await self.get(path, params=params)
+        except NotFound:
+            return None
+
+    @staticmethod
+    def _parse(response: httpx.Response, path: str) -> Any:
+        """Return the `data` payload of a tfmkt response, or raise the TransfermarktError matching the failure."""
+        metadata = {"url": str(response.request.url), "status_code": response.status_code}
+        if response.headers.get("x-amzn-waf-action") or (response.status_code == 202 and not response.content):
+            raise UpstreamBlocked(f"Upstream blocked the request (WAF challenge) for {path}", **metadata)
+        if response.status_code == 404:
+            raise NotFound(f"Not found: {path}", **metadata)
+        if response.status_code in (403, 429):
+            raise UpstreamBlocked(f"Upstream refused the request ({response.status_code})", **metadata)
+        if response.status_code != 200:
+            raise UpstreamError(f"Unexpected upstream status {response.status_code}", **metadata)
+        try:
+            body = response.json()
+        except ValueError:
+            raise UpstreamError(f"Upstream returned invalid JSON for {path}", **metadata)
+        if not isinstance(body, dict) or not body.get("success") or "data" not in body:
+            raise UpstreamError(f"Unexpected upstream payload for {path}", **metadata)
+        return body["data"]
+
+    async def get_batch(self, route: str, ids: Iterable[str | int | None]) -> dict[str, dict]:
+        """
+        Fetch entities from a batch route (`/players`, `/clubs`, `/competitions`) and index them by ID.
+
+        IDs that upstream does not return are simply absent from the result; callers must handle the gap.
+        """
+        unique_ids = sorted({str(i) for i in ids if i not in (None, "")})
+        chunks = [unique_ids[i : i + BATCH_SIZE] for i in range(0, len(unique_ids), BATCH_SIZE)]
+        results = await gather(*(self.get(route, params=[("ids[]", i) for i in chunk]) for chunk in chunks))
+        return {str(entity["id"]): entity for data in results for entity in data or []}
+
+    async def attributes(self) -> dict:
+        """Reference data: countries, positions, competition types, confederations, injuries, etc."""
+        return await self.get("/attributes", reference=True)
+
+    async def quick_search(self, term: str, page: int) -> dict:
+        """Search players, clubs, competitions and coaches; returns IDs per category."""
+        return await self.get("/quick-search", params=[("term", term), ("page", page)])
+
+    async def player(self, player_id: str) -> dict:
+        """Fetch a player record."""
+        return await self.get(f"/player/{player_id}")
+
+    async def player_market_value_history(self, player_id: str) -> dict:
+        """Fetch a player's market value history and current value."""
+        return await self.get(f"/player/{player_id}/market-value-history")
+
+    async def player_transfer_history(self, player_id: str) -> Optional[dict]:
+        """None when the player has no transfer history (upstream answers 404)."""
+        return await self.get_optional(f"/transfer/history/player/{player_id}")
+
+    async def player_injuries(self, player_id: str) -> dict:
+        """Fetch a player's injury history."""
+        return await self.get(f"/player/{player_id}/injury")
+
+    async def player_performance_games(self, player_id: str) -> dict:
+        """Fetch one performance record per match of the player's club."""
+        return await self.get(f"/player/{player_id}/performance-game")
+
+    async def player_achievements(self, player_id: str) -> dict:
+        """Fetch a player's titles and awards (one record per title won)."""
+        return await self.get(f"/player/{player_id}/achievement")
+
+    async def player_market_value_ranking(self, player_id: str) -> Optional[dict]:
+        """None when the player has no ranking (upstream answers 404)."""
+        return await self.get_optional(f"/player/{player_id}/market-value-ranking")
+
+    async def player_national_career(self, player_id: str) -> dict:
+        """Fetch the national teams a player has played for."""
+        return await self.get(f"/player/{player_id}/national-career-history")
+
+    async def player_absences(self, player_id: str) -> dict:
+        """Fetch a player's non-injury absences."""
+        return await self.get(f"/player/{player_id}/absence")
+
+    async def coach(self, coach_id: str) -> dict:
+        """Fetch a coach record."""
+        return await self.get(f"/coach/{coach_id}")
+
+    async def coaches(self, ids: Iterable[str | int | None]) -> dict[str, dict]:
+        """Fetch coach records by ID, indexed by ID."""
+        return await self.get_batch("/coaches", ids)
+
+    async def country_clubs(self, country_id: int) -> dict:
+        """Fetch the limited club directory for a country; no upstream pagination is available."""
+        return await self.get(f"/country/{country_id}/club")
+
+    async def club(self, club_id: str) -> dict:
+        """Fetch a club record."""
+        return await self.get(f"/club/{club_id}")
+
+    async def club_squad(self, club_id: str, season_id: Optional[str] = None) -> dict:
+        """Fetch a club's squad for a season (current squad by default)."""
+        return await self.get(f"/club/{club_id}/squad", params=_season(season_id))
+
+    async def club_achievements(self, club_id: str) -> dict:
+        """Fetch a club's titles (one record per title won)."""
+        return await self.get(f"/club/{club_id}/achievement")
+
+    async def club_coach(self, club_id: str) -> Optional[dict]:
+        """None when the club has no head coach on record (upstream answers 404)."""
+        return await self.get_optional(f"/club/{club_id}/coach")
+
+    async def club_stadium(self, club_id: str) -> Optional[dict]:
+        """None when the club has no stadium (upstream answers 404)."""
+        return await self.get_optional(f"/club/{club_id}/stadium")
+
+    async def competition_clubs(self, competition_id: str, season_id: Optional[str] = None) -> dict:
+        """Fetch the member clubs of a competition season (current by default)."""
+        return await self.get(f"/competition/{competition_id}/club", params=_season(season_id))
+
+    async def competition_table(self, competition_id: str, season_id: Optional[str] = None) -> dict:
+        """Fetch a competition's league table(s) for a season (current by default)."""
+        return await self.get(f"/competition/{competition_id}/table", params=_season(season_id))
+
+    async def competition_seasons(self, competition_id: str) -> dict:
+        """Fetch the seasons available for a competition."""
+        return await self.get(f"/competition/{competition_id}/season")
+
+    async def game(self, game_id: str) -> dict:
+        """Fetch a match: lineups, events, score and officials."""
+        return await self.get(f"/game/{game_id}")
+
+    async def stadium(self, stadium_id: str) -> Optional[dict]:
+        """None when the stadium is unknown (upstream answers 404)."""
+        return await self.get_optional(f"/stadium/{stadium_id}")
+
+    async def competitions(self, ids: Iterable[str | int | None]) -> dict[str, dict]:
+        """Fetch competition records by ID, indexed by ID."""
+        return await self.get_batch("/competitions", ids)
+
+    async def clubs(self, ids: Iterable[str | int | None]) -> dict[str, dict]:
+        """Fetch club records by ID, indexed by ID."""
+        return await self.get_batch("/clubs", ids)
+
+    async def players(self, ids: Iterable[str | int | None]) -> dict[str, dict]:
+        """Fetch player records by ID, indexed by ID."""
+        return await self.get_batch("/players", ids)
+
+
+def _season(season_id: Optional[str]) -> Optional[list[tuple[str, str]]]:
+    """Query parameters selecting a season, or None for the current season."""
+    return [("season", season_id)] if season_id else None

transfermarkt_api/tfmkt/concurrency.py

@@ -0,0 +1,17 @@
+"""Ordered fan-out with cleanup before failures leave the SDK."""
+
+import asyncio
+from collections.abc import Awaitable
+from typing import Any
+
+
+async def gather(*awaitables: Awaitable[Any]) -> list[Any]:
+    """Return results in input order, cancelling and awaiting siblings on any failure."""
+    tasks = [asyncio.ensure_future(awaitable) for awaitable in awaitables]
+    try:
+        return await asyncio.gather(*tasks)
+    except BaseException:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        raise

transfermarkt_api/tfmkt/freshness.py

@@ -0,0 +1,38 @@
+"""
+Track when the upstream data behind a response was fetched, so `updatedAt` stays truthful when served from cache.
+
+`fetch_scope()` starts a per-call record before assembly and model validation. The client reports
+each response it uses, fresh or cached, and `data_fetched_at()` returns the oldest fetch time. The record is a
+mutable list shared through a context variable, so fetches made inside `asyncio.gather` child tasks are seen by
+the request.
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from datetime import UTC, datetime
+from typing import Optional
+
+_fetch_times: ContextVar[Optional[list[datetime]]] = ContextVar("tfmkt_fetch_times", default=None)
+
+
+@contextmanager
+def fetch_scope() -> Iterator[None]:
+    """Isolate one assembly operation, restoring the calling context even on failure."""
+    token = _fetch_times.set([])
+    try:
+        yield
+    finally:
+        _fetch_times.reset(token)
+
+
+def record_fetch(fetched_at: datetime) -> None:
+    """Record when a response used by the current request was fetched from upstream."""
+    fetch_times = _fetch_times.get()
+    if fetch_times is not None:
+        fetch_times.append(fetched_at)
+
+
+def data_fetched_at() -> datetime:
+    """Oldest fetch time recorded for the current request, or now when nothing was fetched."""
+    return min(_fetch_times.get() or [], default=None) or datetime.now(UTC).replace(tzinfo=None)

transfermarkt_api/tfmkt/reference.py

@@ -0,0 +1,116 @@
+"""Lookups into tfmkt reference data (`/attributes`) and small helpers shared by JSON-backed services."""
+
+import math
+from typing import Any, Optional, Union
+
+from transfermarkt_api.tfmkt.client import TfmktClient
+
+TRANSFERMARKT_URL = "https://www.transfermarkt.com"
+RETIRED_CLUB_ID = "123"
+SEARCH_PAGE_SIZE = 10  # quick-search returns 10 IDs per category per page
+
+
+class Reference:
+    """Indexed view of `/attributes`."""
+
+    def __init__(self, attributes: dict) -> None:
+        """Index the `/attributes` lists by ID."""
+        self.countries = {c["id"]: c for c in attributes.get("countries", [])}
+        self.confederations = {c["id"]: c for c in attributes.get("confederations", [])}
+        self.competition_types = {c["id"]: c for c in attributes.get("competitionTypes", [])}
+        self.contracts = {c["id"]: c for c in attributes.get("contracts", [])}
+        self.positions = {p["id"]: p for p in attributes.get("positions", [])}
+
+    def country(self, country_id: Optional[Union[int, str]]) -> dict:
+        """Record of a country, or an empty dict if unknown."""
+        return self.countries.get(_int(country_id)) or {}
+
+    def country_name(self, country_id: Optional[Union[int, str]]) -> Optional[str]:
+        """Name of a country, or None if unknown."""
+        return self.country(country_id).get("name")
+
+    def country_names(self, *country_ids: Optional[Union[int, str]]) -> list[str]:
+        """Names of the known countries among the given IDs, in order."""
+        return [name for name in (self.country_name(i) for i in country_ids) if name]
+
+    def confederation_name(self, confederation_id: Optional[Union[int, str]]) -> Optional[str]:
+        """Short name of a confederation (e.g. UEFA), or None if unknown."""
+        return self.confederations.get(_int(confederation_id), {}).get("name")
+
+    def competition_type_name(self, type_id: Optional[Union[int, str]]) -> Optional[str]:
+        """Name of a competition type (e.g. First Tier), or None if unknown."""
+        return self.competition_types.get(_int(type_id), {}).get("name")
+
+    def position_name(self, position_id: Optional[Union[int, str]]) -> Optional[str]:
+        """Name of a position (e.g. Right Winger), or None if unknown."""
+        return self.positions.get(_int(position_id), {}).get("name")
+
+    def contract_option_name(self, option_id: Optional[Union[int, str]]) -> Optional[str]:
+        """Name of a contract option, or None if unknown."""
+        return self.contracts.get(_int(option_id), {}).get("name")
+
+
+async def get_reference(tfmkt: TfmktClient) -> Reference:
+    """Fetch `/attributes` (cached) and index it."""
+    return Reference(await tfmkt.attributes())
+
+
+def _int(value: Any) -> Optional[int]:
+    """Convert to int, or None when the value is not a number."""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def value_of(money: Optional[dict]) -> Optional[int]:
+    """Numeric value of a tfmkt money object (`{"value": 15000000, "currency": "EUR", ...}`)."""
+    if not money or money.get("value") is None:
+        return None
+    return int(money["value"])
+
+
+def market_value_of(money: Optional[dict]) -> Optional[int]:
+    """Like `value_of`, but 0 means "no valuation" (the website shows "-"), so it becomes None."""
+    return value_of(money) or None
+
+
+def full_url(relative_url: Optional[str]) -> Optional[str]:
+    """Absolute website URL for a relative upstream URL."""
+    return f"{TRANSFERMARKT_URL}{relative_url}" if relative_url else None
+
+
+def season_label(season_id: Optional[Union[int, str]]) -> Optional[str]:
+    """Split-year season label used by the website, e.g. 2025 -> "25/26"."""
+    year = _int(season_id)
+    if year is None:
+        return None
+    return f"{year % 100:02d}/{(year + 1) % 100:02d}"
+
+
+def last_page_number(total: Optional[int], page_size: int = SEARCH_PAGE_SIZE) -> int:
+    """Number of pages needed for `total` results (at least 1)."""
+    return max(1, math.ceil((total or 0) / page_size))
+
+
+def current_assignment(player: dict) -> Optional[dict]:
+    """The player's current club assignment. Selected by type: national-team assignments can come first."""
+    return next((a for a in player.get("clubAssignments") or [] if a.get("type") == "current"), None)
+
+
+def date_of_birth(player: dict) -> Optional[str]:
+    """ISO date of birth, or None when upstream marks it unknown."""
+    life = player.get("lifeDates") or {}
+    return None if life.get("isDateOfBirthUnknown") else life.get("dateOfBirth")
+
+
+def height_cm(player: dict) -> Optional[int]:
+    """Height in centimetres (upstream gives metres)."""
+    height = (player.get("attributes") or {}).get("height")
+    return round(height * 100) if height else None
+
+
+def nationality_ids(player: dict) -> tuple:
+    """First and second nationality country IDs."""
+    nationalities = (player.get("nationalityDetails") or {}).get("nationalities") or {}
+    return nationalities.get("nationalityId"), nationalities.get("secondNationalityId")

transfermarkt_api-5.0.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: transfermarkt-api
+Version: 5.0.0
+Summary: Async Python SDK and HTTP service for Transfermarkt data
+Author-email: Felipe Allegretti <felipe@allegretti.me>
+License: MIT
+License-File: LICENSE
+Requires-Python: <3.14,>=3.12
+Requires-Dist: cachetools<8,>=7.2
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: pydantic<3,>=2.13
+Provides-Extra: server
+Requires-Dist: fastapi<1,>=0.142.2; extra == 'server'
+Requires-Dist: limits<6,>=5.8; extra == 'server'
+Requires-Dist: pydantic-settings<3,>=2.15; extra == 'server'
+Requires-Dist: uvicorn[standard]<1,>=0.54; extra == 'server'
+Description-Content-Type: text/markdown
+
+# transfermarkt-api
+
+An async Python SDK and RESTful API (FastAPI) for football data from [Transfermarkt](https://www.transfermarkt.com/): players, clubs and competitions.
+
+Since version 4.0.0, data comes from Transfermarkt's JSON API (`tmapi.transfermarkt.technology`), the same API the website uses, instead of scraping HTML pages. The website blocks requests from most cloud hosts, which broke v3 deployments; the JSON API does not. See [CHANGELOG.md](CHANGELOG.md) for what changed in the response format.
+
+Please note that the deployed application is used only for testing purposes and is rate limited to 2 requests
+every 3 seconds per client IP. If you'd like to customize it, consider hosting in your own cloud service.
+
+The JSON API is internal to Transfermarkt and undocumented: it can change without notice. This project's MIT license covers its code, not the data; check [Transfermarkt's terms](https://www.transfermarkt.com/intern/) before using the data in your own services.
+
+### Python SDK
+
+Install the library without server dependencies:
+
+```bash
+pip install transfermarkt-api
+# Until the SDK release is published, install from this repository:
+# pip install .
+```
+
+Release setup and the publishing procedure are documented in [Python package releases](docs/releases.md).
+
+```python
+import asyncio
+
+from transfermarkt_api import Transfermarkt
+
+
+async def main() -> None:
+    async with Transfermarkt() as tm:
+        squad = await tm.club_players("985")
+        for player in squad.players:
+            print(player.shirt_number, player.name, player.position, player.market_value)
+        print(squad.model_dump(mode="json", by_alias=True))
+
+
+asyncio.run(main())
+```
+
+The facade has one method per data endpoint: `player_profile`, `player_transfers`, `club_players`,
+`competition_clubs`, `competition_table`, `game`, and the remaining methods listed in the
+[SDK method table](docs/plans/0001-python-sdk.md#public-contract). Methods return typed Pydantic models exported
+from `transfermarkt_api.schemas`. Nested models remain available in their resource modules. Use string entity
+and season IDs, integer country IDs, and 1-based page numbers. Calls return one page; callers control pagination.
+
+Constructor settings are explicit: `base_url`, `timeout` (seconds, `httpx.Timeout`, or `None`),
+`max_concurrency` (default `10`), `transport`, and `cache`. The SDK reads no `.env` or environment settings on import.
+`CacheConfig(ttl=600, reference_ttl=86400, max_entries=2000)` configures per-client caching. Pass `cache=None` to
+disable both response and reference caches so every request reaches the transport.
+
+One client supports concurrent calls within one event loop. Its async context manager, or explicit `aclose()`,
+closes the HTTP client and supplied transport. Do not share a supplied transport across client lifetimes unless
+your wrapper owns and controls its closure. Cache hits remain local to each SDK instance.
+
+The SDK raises `NotFound`, `UpstreamBlocked`, `UpstreamTimeout`, `UpstreamError`, or `EndpointUnavailable`, all
+derived from `TransfermarktError` and exported at the package root. Available upstream URL/status metadata lives
+on `error.url` and `error.status_code`; the status is the upstream status, not the server's mapped HTTP status.
+The unsupported `player_jersey_numbers` method raises `EndpointUnavailable` without fetching data.
+Invalid constructor/page/country arguments raise `ValueError`. Custom transport exceptions propagate unchanged.
+
+### Custom transports and replay
+
+Supply an `httpx.AsyncBaseTransport` to control every upstream request, including reference lookups, batches,
+and per-player fan-out. The SDK bounds in-flight concurrency; the caller's transport owns rate limits, retries,
+proxy selection, recording and circuit breakers. The SDK performs no automatic retries.
+
+```python
+import httpx
+
+from transfermarkt_api import Transfermarkt
+
+# Run inside an async function. A custom browser-capable backend can implement the same transport interface.
+async with Transfermarkt(
+    transport=httpx.AsyncHTTPTransport(proxy="http://127.0.0.1:8080"),
+    cache=None,
+) as tm:
+    squad = await tm.club_players("985", season_id="2024")
+```
+
+[Recording and replay examples](examples/transports.py) wrap a caller-selected backend and save the response
+before SDK parsing. Persist the method, full URL with repeated query parameters, status, relevant headers (including
+`x-amzn-waf-action`), decoded body, and original fetch timestamp. The example store is in memory; replace it with
+durable storage in your application. When reconstructing decoded responses, drop content-encoding/content-length
+headers so the body is not decoded twice.
+
+A replay transport returns an `httpx.Response` with
+`extensions={"transfermarkt_fetched_at": captured_datetime}`. This optional metadata accepts naive or timezone-aware
+datetimes. Aware inputs are converted to UTC; naive inputs are interpreted as UTC. `updatedAt` retains its existing
+JSON shape without a timezone suffix and always represents UTC. Without metadata, it reports the current UTC fetch
+time. Each model reports the oldest fetch time used in that call, including cache hits. Exact replay
+needs the same response bodies and timestamps. Missing recordings must raise a transport error rather than fetch
+live data. Batch URLs are stable; concurrent request completion order is not part of the replay key.
+
+```python
+from examples.transports import RecordingTransport, ReplayTransport
+
+records = {}
+async with Transfermarkt(transport=RecordingTransport(httpx.AsyncHTTPTransport(), records), cache=None) as tm:
+    captured = await tm.club_players("985")
+async with Transfermarkt(transport=ReplayTransport(records), cache=None) as tm:
+    replayed = await tm.club_players("985")
+assert captured == replayed
+```
+
+The examples and HTTP server are repository files. The wheel installs only the `transfermarkt_api` package,
+avoiding collisions with a consumer's own `app` package. The `server` extra installs the server dependencies;
+run `uvicorn app.main:app` from a repository checkout, or use the Docker image.
+
+### API Swagger
+https://transfermarkt-api.fly.dev/
+
+### Endpoints
+
+| Endpoint | Notes |
+| --- | --- |
+| `GET /players/search/{player_name}?page_number=` | 10 results per page |
+| `GET /players/{player_id}/profile` | |
+| `GET /players/{player_id}/market_value` | |
+| `GET /players/{player_id}/transfers` | Transfer type, age, contract dates, remaining contract days, and each club's league and country at the time |
+| `GET /players/{player_id}/stats` | Per season, competition and club; club competitions only |
+| `GET /players/{player_id}/matches?season_id=&page_number=` | Past matches of the player's teams, most recent first, 50 per page; no upcoming fixtures |
+| `GET /players/{player_id}/injuries?page_number=` | 15 injuries per page |
+| `GET /players/{player_id}/absences?page_number=` | Suspensions, call-ups, leave; 15 per page |
+| `GET /players/{player_id}/achievements` | Titles and awards with season, club and competition |
+| `GET /players/{player_id}/national_career` | Senior and youth national teams |
+| `GET /players/{player_id}/jersey_numbers` | `501`: no data source |
+| `GET /countries/` | Country IDs and metadata, including historical entries; cached for 24 hours |
+| `GET /clubs/?country_id=` | Available club IDs and names for a country; limited upstream coverage, no pagination |
+| `GET /clubs/search/{club_name}?page_number=` | 10 results per page |
+| `GET /clubs/{club_id}/profile` | Squad value details, historical names and stadium details |
+| `GET /clubs/{club_id}/players?season_id=` | Current squad by default; shirt number and captaincy for the selected season |
+| `GET /clubs/{club_id}/achievements` | Club titles by season |
+| `GET /coaches/search/{coach_name}?page_number=` | 10 results per page |
+| `GET /coaches/{coach_id}/profile` | |
+| `GET /competitions/search/{competition_name}?page_number=` | 10 results per page |
+| `GET /competitions/{competition_id}/clubs?season_id=` | Current season by default |
+| `GET /competitions/{competition_id}/table?season_id=` | League table; one table per group for group stages |
+| `GET /competitions/{competition_id}/seasons` | Valid `season_id` values |
+| `GET /games/{game_id}` | Score, lineups, coaches, stadium, team stats, goals, cards and substitutions |
+
+Errors: `404` unknown ID, `501` endpoint without data source, `502` unexpected upstream response, `503` upstream blocked or refused the request, `504` upstream timeout.
+
+Fields without an upstream value are returned as `null`. `updatedAt` is when the underlying data was fetched from Transfermarkt; responses are cached for 10 minutes by default.
+
+### Running Locally
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+````bash
+# Clone the repository
+$ git clone https://github.com/felipeall/transfermarkt-api.git
+
+# Go to the project's root folder
+$ cd transfermarkt-api
+
+# Install Python 3.12 and the dependencies
+$ uv sync --extra server
+
+# Start the API server
+$ uv run uvicorn app.main:app --reload
+
+# Access the API local page
+$ open http://localhost:8000/
+````
+
+### Running Tests
+
+````bash
+# Offline tests (recorded upstream responses, no network)
+$ uv run --extra server pytest
+
+# Live smoke tests against Transfermarkt's JSON API
+$ uv run --extra server pytest -m live
+
+# Re-record upstream fixtures and response snapshots
+$ rm -rf tests/fixtures/tfmkt && uv run python scripts/capture_fixtures.py
+````
+
+### Running via Docker
+
+````bash
+# Clone the repository
+$ git clone https://github.com/felipeall/transfermarkt-api.git
+
+# Go to the project's root folder
+$ cd transfermarkt-api
+
+# Build the Docker image
+$ docker build -t transfermarkt-api .
+
+# Instantiate the Docker container
+$ docker run -d -p 8000:8000 transfermarkt-api
+
+# Access the API local page
+$ open http://localhost:8000/
+````
+
+### Environment Variables
+
+| Variable                      | Description                                                                                            | Default                                  |
+|-------------------------------|--------------------------------------------------------------------------------------------------------|------------------------------------------|
+| `RATE_LIMITING_ENABLE`        | Enable rate limiting feature for API calls                                                             | `false`                                  |
+| `RATE_LIMITING_FREQUENCY`     | Requests allowed per client IP across all routes, in [limits notation](https://limits.readthedocs.io/en/stable/quickstart.html#rate-limit-string-notation) | `2/3seconds`                             |
+| `TFMKT_BASE_URL`              | Transfermarkt JSON API base URL                                                                        | `https://tmapi.transfermarkt.technology` |
+| `TFMKT_TIMEOUT_SECONDS`       | Timeout for each upstream request                                                                      | `15`                                     |
+| `TFMKT_MAX_CONCURRENCY`       | Maximum concurrent upstream requests across the whole server                                          | `10`                                     |
+| `CACHE_TTL_SECONDS`           | How long successful upstream responses are cached                                                      | `600`                                    |
+| `CACHE_REFERENCE_TTL_SECONDS` | Cache duration for reference data (countries, positions, ...)                                          | `86400`                                  |
+| `CACHE_MAX_ENTRIES`           | Maximum number of cached upstream responses                                                            | `2000`                                   |
+
+Rate limits apply to the API routes only: `/health`, the docs (`/`, `/docs`, `/redoc`) and `/openapi.json` are not
+counted. They are counted per client IP: the `Fly-Client-IP` header set by the Fly.io proxy, or the address of the
+connection when that header is missing. `X-Forwarded-For` is not trusted. Behind another reverse proxy, all
+requests share the proxy's address, and outside Fly.io clients can send `Fly-Client-IP` themselves, so adjust
+`client_ip` in `app/main.py` before enabling rate limiting on another host.