🏈 CFL SDK

A modern Python SDK for the Canadian Football League API using httpx.

Features

• Full type hints using modern Python typing
• Comprehensive API coverage (most endpoints supported)
• Error handling and logging

Installation

pip install cfl-sdk

With Poetry

poetry add cfl-sdk

Quick Start

from cfl import CFLClient

# Create client
client = CFLClient()

# Get teams
teams = client.get_teams()
for team in teams:
    print(f"{team['name']} ({team['abbreviation']})")

# Get fixtures for a season
fixtures = client.get_fixtures(season_id=34)  # 2025 season

# Get player stats
player_stats = client.get_player_stats(season_id=34)  # 2025 season

API Reference

Teams

# Get all teams
teams = client.get_teams()

# Get a specific team
team = client.get_team(team_id=1)

Venues

# Get all venues
venues = client.get_venues()

# Get specific venue
venue = client.get_venue(venue_id=1)

Seasons

# Get all seasons (with optional pagination)
seasons = client.get_seasons(page=1, limit=50)

# Get specific season
season = client.get_season(season_id=34)  # 2025 season

Fixtures (Games)

# Get all fixtures (with optional pagination)
fixtures = client.get_fixtures(page=1, limit=50)

# Get fixtures for a season
fixtures = client.get_fixtures(season_id=34, page=1, limit=50)  # 2025 season

Rosters

# Get all rosters
rosters = client.get_rosters()

# Get specific roster
roster = client.get_roster(roster_id=1)

Ledger (Transactions)

# Get transactions for a year
transactions = client.get_ledger(year=2024)

Team Stats

# Get team stats
team_stats = client.get_team_stats()

# Get team stats for a season
team_stats = client.get_team_stats(season_id=34)  # 2025 season

# Get specific team stats
team_stat = client.get_team_stat(team_stats_id=122345)

Player Stats

# Get player stats (with optional pagination and season filter)
player_stats = client.get_player_stats(season_id=34, page=1, limit=50)

# Get specific player stats
player_stat = client.get_player_stat(player_stats_id=1629968)

# Get player stats with photo URL
player_stat = client.get_player_pims(player_id=168507)

Standings

# Get standings for a year (2023-2025 supported)
standings = client.get_standings(year=2024)

Leaderboard

# Get player leaderboard for different stats for a year (2023-2025 supported)
leaderboard = client.get_leaderboards(season=2024)

Error Handling

The SDK provides specific error types:

• CFLAPIConnectionError: For connection issues
• CFLAPITimeoutError: For request timeouts
• CFLAPINotFoundError: For 404 responses
• CFLAPIAuthenticationError: For auth issues
• CFLAPIValidationError: For invalid requests
• CFLAPIServerError: For server errors

from cfl import CFLClient, CFLAPINotFoundError

client = CFLClient()

try:
    team = client.get_team(team_id=999999)
except CFLAPINotFoundError:
    print("Team not found")

Using with Context Manager

with CFLClient() as client:
    teams = client.get_teams()
    # Client will be closed automatically

Acknowledgements & Disclaimer

Thank you to the Canadian Football League (CFL) for providing a public API.

This is an unofficial SDK and is not affiliated with, endorsed, or sponsored by the Canadian Football League (CFL).

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue for any bugs or feature requests.

License

This project is licensed under the MIT License. See the LICENSE file for more details.