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

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 errors
  • AuthenticationError — 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

MIT