soccer-info 0.1.1

Python SDK for Soccer Football Info API via RapidAPI

Soccer Info - Python SDK for Soccer Football Info API

A Python SDK for accessing the Soccer Football Info API via RapidAPI. Provides both synchronous and asynchronous clients with typed request builders and Pydantic response models for soccer championship data.

Scope and Limitations

This SDK currently implements the Championship API endpoints from the Soccer Football Info API:

• Championships List - Browse and filter available soccer championships by country
• Championship Details - Get detailed championship data including seasons, groups, and team standings

The Soccer Football Info API offers 29 total endpoints covering matches, live scores, teams, players, managers, referees, stadiums, and more. This SDK currently focuses on championship data. For the complete API catalog, visit the Soccer Football Info API documentation on RapidAPI.

Future versions may expand to include additional endpoints based on community needs.

Quick Start

Installation

pip install soccer-info

Requirements

• Python 3.13 or higher
• RapidAPI account (free tier available)
• RapidAPI key for Soccer Football Info API

Get your RapidAPI key:

1. Sign up at RapidAPI
2. Subscribe to Soccer Football Info API
3. Find your API key in the API dashboard

Basic Usage

import soccer_info

# Create client with default settings (uses RAPIDAPI_SOCCER_INFO_KEY env var)
client = soccer_info.quick_client()

# Get list of championships
championships = client.championships.get_list()
print(f"Found {len(championships.result)} championships")

# Get detailed championship data
championship_detail = client.championships.get_by_id("5778d8e65b65c7f9")
print(f"Championship: {championship_detail.first_result.name}")
print(f"Country: {championship_detail.first_result.country}")

API Key Setup

The SDK provides multiple flexible ways to configure your RapidAPI key:

Quick Start (Default)

Set the RAPIDAPI_SOCCER_INFO_KEY environment variable and use quick_client():

import soccer_info

client = soccer_info.quick_client()
championships = client.championships.get_list()

All Configuration Options

1. Environment Variable (Default)

import soccer_info

# Uses RAPIDAPI_SOCCER_INFO_KEY environment variable
client = soccer_info.quick_client()

2. Direct API Key

from soccer_info.settings import SettingsBuilder
import soccer_info

settings = SettingsBuilder().with_api_key(key="your-rapidapi-key-here").build()
client = soccer_info.quick_client(settings)

3. Custom Environment Variable

from soccer_info.settings import SettingsBuilder
import soccer_info

settings = SettingsBuilder().with_api_key(environment="MY_CUSTOM_API_KEY").build()
client = soccer_info.quick_client(settings)

4. Provider Function

from soccer_info.settings import SettingsBuilder
import soccer_info

def get_api_key():
    # Load from secure vault, file, or other source
    return "your-api-key"

settings = SettingsBuilder().with_api_key(key_provider=get_api_key).build()
client = soccer_info.quick_client(settings)

Advanced Usage

Custom Client Configuration

from soccer_info.settings import SettingsBuilder
from soccer_info.client import HTTPXClient

# Build custom settings
settings = (
    SettingsBuilder()
    .with_api_key(key="your-api-key")
    .with_base_url("https://soccer-football-info.p.rapidapi.com")
    .with_host("soccer-football-info.p.rapidapi.com")
    .build()
)

# Create client with custom settings
client = HTTPXClient(settings)
championships = client.championships.get_list()

Context Manager for Resource Management

import soccer_info

# Automatically closes HTTP client when done
with soccer_info.quick_client() as client:
    championships = client.championships.get_list()
    for champ in championships.result:
        detail = client.championships.get_by_id(champ.id)
        print(f"{detail.first_result.name}")

Asynchronous Client

The async client includes built-in request throttling to respect API rate limits. See settings.py for default configuration values.

import asyncio
import soccer_info

async def main():
    # Create async client with context manager
    async with soccer_info.quick_async_client() as client:
        # Fetch data asynchronously
        championships = await client.championships.get_list()
        
        # Fetch multiple championships concurrently
        # Throttling is automatically handled
        tasks = [
            client.championships.get_by_id(champ.id)
            for champ in championships.result[:5]
        ]
        results = await asyncio.gather(*tasks)
        
        for detail in results:
            print(f"{detail.first_result.name}")

asyncio.run(main())

Rate Limit Monitoring

import soccer_info

client = soccer_info.quick_client()
response = client.championships.get_list()

# Access rate limit information from response headers
headers = response.response_headers
print(f"Rate limit: {headers.rate_limit_remaining}/{headers.rate_limit_limit}")
print(f"Resets in: {headers.hours_to_reset} hours")
print(f"Resets in: {headers.rate_limit_reset} seconds")

Saving Responses to JSON

from pathlib import Path
import soccer_info

client = soccer_info.quick_client()
response = client.championships.get_list()

# Save full response to JSON file
response.save_pretty_json(Path("championships.json"))

# Save individual championship detail
detail = client.championships.get_by_id("5778d8e65b65c7f9")
detail.save_pretty_json(Path("championship_detail.json"))

Setting Default Language

from soccer_info.settings import SettingsBuilder
from soccer_info.client import HTTPXClient

settings = SettingsBuilder().with_api_key().build()

# Set default language for all requests
client = HTTPXClient(settings, default_language="es_ES")

# Uses Spanish by default
championships = client.championships.get_list()

# Override for specific request
championships_german = client.championships.get_list(language="de_DE")

API Reference

Client Creation Functions

• quick_client() - Create synchronous client with default settings
• quick_async_client() - Create asynchronous client with default settings

Championship Methods

• get_list(page=None, country=None, language=None) - Retrieve paginated list of championships with optional country filter
• get_by_id(championship_id, language=None) - Get detailed championship data including seasons, groups, and standings

Response Models

• ChampionshipListResponse - Paginated list of championship items
• ChampionshipViewResponse - Detailed championship with seasons and standings
• ChampionshipListItem - Basic championship information (id, name, has_image)
• ChampionshipDetail - Full championship data with seasons
• Season - Season information with date range and groups
• Group - League group with standings table
• TableEntry - Team standing with position, points, wins, draws, losses, goals
• Team - Team reference (id, name)

Response Properties

All responses include:

• status - HTTP status code
• errors - List of error messages
• result - List of result items
• pagination - Pagination information
• response_headers - HTTP headers including rate limit info
• is_success - Boolean property indicating successful response
• first_result - Convenience property for first result item
• pagination_info - Convenience property for pagination data

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions! Here's how you can help:

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/your-username/soccer-info.git
   cd soccer-info
   

3. Set up development environment:

   # Create virtual environment
   python -m venv .venv
   
   # Activate virtual environment
   # Windows:
   .venv\Scripts\activate
   # Linux/Mac:
   source .venv/bin/activate
   
   # Install in development mode with dev dependencies
   pip install -e .
   pip install -r requirements-dev.txt
   

Development Environment

The project includes:

• python-dotenv for managing environment variables during development
• Example scripts in the examples/ directory demonstrating both sync and async usage
• Type checking support with py.typed marker

Create a .env file in the project root for development:

RAPIDAPI_SOCCER_INFO_KEY=your-development-api-key

Project Structure

The SDK follows a clean architecture pattern:

soccer_info/
├── __init__.py          # Public API exports and quick_client()
├── py.typed             # PEP 561 type marker
├── client/              # Client implementations (sync/async)
├── requests_/           # Request components (headers, parameters)
├── responses/           # Response models (Pydantic)
└── settings/            # Configuration management

Code Style

• Follow PEP 8 guidelines
• Use type hints for all function signatures
• Document public APIs with docstrings
• Keep response models aligned with API structure

Code of Conduct

Be respectful and constructive in all interactions. This project follows standard open source community guidelines.