football-api
A minimal Python client for the football-data.org API v4.
Provides both sync and async interfaces with full type safety via Pydantic models.
Installation
pip install football-api
Quick Start
Sync
from football_api import FootballClient
with FootballClient(api_key="YOUR_TOKEN") as client:
# Premier League standings
standings = client.get_standings("PL")
for entry in standings.standings[0].table:
print(f"{entry.position}. {entry.team.name} — {entry.points} pts")
# Today's matches
matches = client.get_matches()
for m in matches.matches:
print(f"{m.home_team.name} vs {m.away_team.name} [{m.status}]")
Async
import asyncio
from football_api import AsyncFootballClient
async def main():
async with AsyncFootballClient(api_key="YOUR_TOKEN") as client:
comp = await client.get_competition("PL")
print(comp.name, comp.current_season.current_matchday)
asyncio.run(main())
Environment Variable
Instead of passing api_key directly, set FOOTBALL_DATA_API_KEY:
export FOOTBALL_DATA_API_KEY="your-token-here"
client = FootballClient() # reads from env
API Methods
| Method | Description |
|---|---|
get_areas() |
List all areas |
get_area(id) |
Get area by ID |
get_competitions(areas=...) |
List competitions |
get_competition(id) |
Get competition by ID or code |
get_standings(comp_id, season=..., matchday=...) |
League table |
get_scorers(comp_id, season=..., limit=...) |
Top scorers |
get_matches(date_from=..., date_to=..., status=...) |
List matches |
get_match(id) |
Get single match |
get_head2head(match_id, limit=...) |
Head-to-head history |
get_competition_matches(comp_id, matchday=..., stage=...) |
Competition matches |
get_team(id) |
Get team details |
get_competition_teams(comp_id, season=...) |
Teams in competition |
get_team_matches(team_id, venue=..., status=...) |
Team matches |
get_person(id) |
Get person (player/coach/referee) |
get_person_matches(person_id, competitions=..., limit=...) |
Person matches |
All methods are available on both FootballClient (sync) and AsyncFootballClient (async).
Error Handling
from football_api import FootballClient, NotFoundError, RateLimitError
with FootballClient(api_key="YOUR_TOKEN") as client:
try:
team = client.get_team(99999)
except NotFoundError:
print("Team not found")
except RateLimitError:
print("Rate limit exceeded, slow down")
Exception hierarchy:
FootballAPIError— base for all API errorsAuthenticationError— invalid or missing token (HTTP 403)NotFoundError— resource not found (HTTP 404)RateLimitError— rate limit exceeded (HTTP 429)ServerError— server-side errors (HTTP 5xx)
Supported Competitions
The free tier includes several major leagues and competitions. See football-data.org for the full list.
Development
git clone https://github.com/ice1x/football-api.git
cd football-api
pip install -e ".[dev]"
pytest
License
Metadata
Release files for football-api 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| football_api-0.1.0.tar.gz | 25.1 kB | Without provenance | Details for football_api-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| football_api-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for football_api-0.1.0-py3-none-any.whl |
Total release size: 33.8 kB
Release files / football_api-0.1.0.tar.gz
| Download URL | football_api-0.1.0.tar.gz |
|---|---|
| Size | 25.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d6d2d765b28a164a0d0255d1385513578eed1e7977fce58bbc52266ad541a521
|
|
BLAKE2b-256 checksum How to use checksums |
e4c5dd78a86e894c3cbe2d9d5c95e8d6d1b076b24c0d5cd906e692d082bf1a89
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / football_api-0.1.0-py3-none-any.whl
| Download URL | football_api-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b605df1de1fe8354de495f406d9c112f29dd69ca5c39064ff072821d09168479
|
|
BLAKE2b-256 checksum How to use checksums |
994594a24791f1329942094ffd4959d40e2e5bc022eca47a9aafd0b2f0924b7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Security for football-api 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.