transfermarkt-api 5.0.0__tar.gz

transfermarkt_api-5.0.0/.gitignore

@@ -0,0 +1,164 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Vercel
+.vercel/

transfermarkt_api-5.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Felipe Allegretti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

transfermarkt_api-5.0.0/PKG-INFO

@@ -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.

transfermarkt_api-5.0.0/README.md

@@ -0,0 +1,216 @@
+# 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.

transfermarkt_api-5.0.0/app/api/api.py

@@ -0,0 +1,11 @@
+from fastapi import APIRouter
+
+from app.api.endpoints import clubs, coaches, competitions, countries, games, players
+
+api_router = APIRouter()
+api_router.include_router(competitions.router, prefix="/competitions", tags=["competitions"])
+api_router.include_router(clubs.router, prefix="/clubs", tags=["clubs"])
+api_router.include_router(players.router, prefix="/players", tags=["players"])
+api_router.include_router(coaches.router, prefix="/coaches", tags=["coaches"])
+api_router.include_router(countries.router, prefix="/countries", tags=["countries"])
+api_router.include_router(games.router, prefix="/games", tags=["games"])

transfermarkt_api-5.0.0/app/api/dependencies.py

@@ -0,0 +1,13 @@
+from typing import Annotated
+
+from fastapi import Depends, Request
+
+from transfermarkt_api import Transfermarkt
+
+
+def get_tfmkt(request: Request) -> Transfermarkt:
+    """Return the shared upstream client created during server startup."""
+    return request.app.state.tfmkt
+
+
+Tfmkt = Annotated[Transfermarkt, Depends(get_tfmkt)]