pip install altsportsdata

from altsportsdata import AltSportsData
import os

client = AltSportsData(api_key=os.getenv('ALTSPORTSDATA_API_KEY'))

# Fetch elite soccer leagues
leagues = client.leagues.list(
    sport_type='Soccer',
    tier='elite'
)

print(leagues.data)

from altsportsdata import AltSportsData

client = AltSportsData(api_key='your-api-key')

from altsportsdata import AltSportsData, RetryConfig

client = AltSportsData(
    api_key='your-api-key',
    base_url='https://api.altsportsdata.com/v1',  # Custom base URL
    timeout=30.0,  # Request timeout in seconds (default: 30)
    retry_config=RetryConfig(
        enabled=True,  # Enable auto-retry (default: True)
        max_retries=3,  # Max retry attempts (default: 3)
        initial_delay=1.0,  # Initial retry delay in seconds
        max_delay=10.0  # Max retry delay in seconds
    ),
    headers={
        'X-Custom-Header': 'value'  # Additional headers
    }
)

# List leagues
leagues = client.leagues.list(
    sport_type='Soccer',
    tier='elite',
    country='GB',
    limit=50,
    offset=0
)

# Get specific league
league = client.leagues.get('league_001')

# Get league statistics
stats = client.leagues.stats()

# Get league fingerprint
fingerprint = client.leagues.fingerprint('league_001')

# Get league valuation
valuation = client.leagues.valuation('league_001')

# Get qualification score
qualification = client.leagues.qualification('league_001')

# Get readiness report
readiness = client.leagues.readiness('league_001')

# Compare leagues
comparison = client.leagues.compare('league_001', 'league_002')

# Find similar leagues
similar = client.leagues.similar('league_001', limit=10)

# Re-evaluate league
client.leagues.evaluate('league_001')

# Search leagues
results = client.discovery.search(
    q='premier league',
    limit=10
)

# Find similar leagues (vector search)
similar = client.discovery.similar('league_001', limit=10)

# Evaluate league
evaluation = client.valuation.evaluate(league_id='league_001')

# Get tier definitions
tiers = client.valuation.tiers()

# List all sports
sports = client.sports.list()

# Get sport archetypes
archetypes = client.sports.archetypes()

# List events
events = client.events.list(
    league_id='league_001',
    date_from='2026-03-01',
    date_to='2026-03-31',
    limit=100
)

# List betting markets
markets = client.markets.list(limit=50)

from altsportsdata import AltSportsData
from altsportsdata.types import (
    League,
    LeagueReadiness,
    LeagueValuation,
    Sport,
    Event,
    Market,
    ListLeaguesResponse
)

client = AltSportsData(api_key='your-api-key')

# Type-safe requests and responses
response: ListLeaguesResponse = client.leagues.list(
    sport_type='Soccer',
    tier='elite'
)

# Type-checked iteration
league: League
for league in response.data:
    print(league.name)  # IDE autocomplete available

from altsportsdata import AltSportsData
from altsportsdata.exceptions import (
    AltSportsDataError,
    ResourceNotFoundError,
    RateLimitError,
    ValidationError,
    AuthenticationError
)

client = AltSportsData(api_key='your-api-key')

try:
    league = client.leagues.get('invalid_id')
except ResourceNotFoundError as e:
    print(f'League not found: {e.message}')
except RateLimitError as e:
    print(f'Rate limit exceeded')
    print(f'Retry after: {e.retry_after} seconds')
except ValidationError as e:
    print(f'Validation failed: {e.details}')
except AuthenticationError:
    print('Invalid API key')
except AltSportsDataError as e:
    print(f'API error: {e.message}')

offset = 0
limit = 100
all_leagues = []

while True:
    response = client.leagues.list(limit=limit, offset=offset)
    all_leagues.extend(response.data)

    if not response.meta.has_more:
        break
    offset += limit

print(f'Total leagues: {len(all_leagues)}')

# Iterator (automatically handles pagination)
all_leagues = []

for league in client.leagues.list_all(tier='elite'):
    all_leagues.append(league)

print(f'Total leagues: {len(all_leagues)}')

# Access rate limit info from response
response = client.leagues.list()

print('Rate Limit Info:')
print(f'  Limit: {response.rate_limit.limit}')
print(f'  Remaining: {response.rate_limit.remaining}')
print(f'  Reset: {response.rate_limit.reset}')

# Auto-retry on rate limit (with exponential backoff)
client = AltSportsData(
    api_key='your-api-key',
    retry_config=RetryConfig(
        enabled=True,
        max_retries=5,
        respect_rate_limits=True  # Wait for rate limit reset
    )
)

# Global timeout
client = AltSportsData(
    api_key='your-api-key',
    timeout=60.0  # 60 seconds
)

# Per-request timeout
league = client.leagues.get('league_001', timeout=10.0)

from altsportsdata import AltSportsData

with AltSportsData(api_key='your-api-key') as client:
    leagues = client.leagues.list(tier='elite')
    print(leagues.data)

# Client automatically closes connections

import asyncio
from altsportsdata import AsyncAltSportsData

async def main():
    async with AsyncAltSportsData(api_key='your-api-key') as client:
        # Concurrent requests
        leagues_task = client.leagues.list(tier='elite')
        sports_task = client.sports.list()
        
        leagues, sports = await asyncio.gather(leagues_task, sports_task)
        
        print(f'Leagues: {len(leagues.data)}')
        print(f'Sports: {len(sports.data)}')

asyncio.run(main())

# .env file
ALTSPORTSDATA_API_KEY=your-api-key
ALTSPORTSDATA_BASE_URL=https://api.altsportsdata.com/v1

import os
from dotenv import load_dotenv
from altsportsdata import AltSportsData

load_dotenv()

client = AltSportsData(
    api_key=os.getenv('ALTSPORTSDATA_API_KEY'),
    base_url=os.getenv('ALTSPORTSDATA_BASE_URL')
)

import logging
from altsportsdata import AltSportsData

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

client = AltSportsData(api_key='your-api-key')

# SDK will log HTTP requests and responses
leagues = client.leagues.list()

import pandas as pd
from altsportsdata import AltSportsData

client = AltSportsData(api_key='your-api-key')

leagues = client.leagues.list(tier='elite')

# Convert to DataFrame
df = pd.DataFrame([league.dict() for league in leagues.data])

print(df[['name', 'country', 'tier', 'founded']])