An async Python SDK and RESTful API (FastAPI) for football data from Transfermarkt: players, clubs, coaches, competitions and matches.

Since version 4.0.0, data comes from Transfermarkt's JSON API, the same API the website uses, instead of scraping HTML pages. Upstream requests can still be blocked or fail; the SDK and service distinguish these failures. See CHANGELOG.md for changes to 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 before using the data in your own services.

Interactive API documentation

Errors: 404 unknown ID, 422 invalid parameters, 429 HTTP client rate limit exceeded, 501 endpoint without data source, 502 unexpected upstream response, 503 upstream blocked or refused the request, 504 upstream timeout. An upstream 429 maps to 503, distinct from the service's own rate limit.

Fields without an upstream value are returned as null. updatedAt represents the oldest upstream fetch used to assemble the response, in UTC without a timezone suffix. Successful upstream payloads are cached for 10 minutes by default; reference data is cached for 24 hours.

Requires Python 3.12 or 3.13. The SDK is published on PyPI. Install it without server dependencies:

pip install transfermarkt-api

Release setup and the publishing procedure are documented in Python package releases.

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. 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. Paginated methods 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. Page numbers, country IDs and concurrency caps must be positive integers. With the default transport, timeouts and connection errors map to SDK exceptions. With an injected transport, its exceptions propagate unchanged, including native httpx errors; callers classify those transport errors themselves.

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.

import asyncio

import httpx

from transfermarkt_api import Transfermarkt


async def main() -> None:
    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")
        print(squad.model_dump(mode="json", by_alias=True))


asyncio.run(main())

The proxy address is an example; configure your own proxy. A browser-capable backend can implement the same transport interface.

Recording and replay examples 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.

Run this recording/replay example from a repository checkout:

import asyncio

import httpx

from examples.transports import RecordingTransport, ReplayTransport
from transfermarkt_api import Transfermarkt


async def main() -> None:
    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


asyncio.run(main())

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.

Requires uv. Run these commands from a repository checkout; the wheel contains the SDK, not the app server package.

# 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 --python 3.12 --extra server

# Start the API server
$ uv run --extra server uvicorn app.main:app --reload

# Access the API local page
$ open http://localhost:8000/

# 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 selected upstream fixtures and API snapshots (makes live requests)
$ uv run --extra server python scripts/capture_fixtures.py clubs_131_players

The capture script retains existing recordings and updates selected URLs and API snapshots. Omit the case-name filter to capture all cases. Review the changed files; the frozen tests/snapshots/v3/ baseline is not regenerated.

# 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/

These settings configure the HTTP server and can be loaded from .env. SDK callers pass constructor arguments instead.

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.