pyapisports 0.2.0

Python library for the https://api-sports.io/ API

PyAPISports

A modern Python client for the API-Sports APIs.

This SDK provides a simple, typed interface to interact with API-Sports endpoints such as Football, Basketball, and more.

Features

• Simple and Pythonic API
• Automatic authentication
• Context-managed client
• Structured response objects
• JSON serialization support
• Easy access to request usage and subscription information

Installation

uv add pyapisports

Quick Start

from api_sports import ApiSportsClient

with ApiSportsClient(api_key="YOUR_API_KEY") as client:
    status = client.football.get_status()

    print(status.account.email)
    print(status.subscription.plan)
    print(status.subscription.active)
    print(status.subscription.end)
    print(status.requests.remaining)
    print(status.requests.usage_percent)
    print(status.to_json(indent=2))

Authentication

You need an API key from API-Sports.

Create a client using your API key:

client = ApiSportsClient(api_key="YOUR_API_KEY")

The client can also be used as a context manager:

with ApiSportsClient(api_key="YOUR_API_KEY") as client:
    ...

This ensures proper session handling and connection cleanup.

Example: Account Status

Retrieve information about your account, subscription, and request usage.

status = client.football.get_status()

Example fields available:

status.account.email
status.subscription.plan
status.subscription.active
status.subscription.end
status.requests.remaining
status.requests.usage_percent

Convert the response to JSON:

status.to_json(indent=2)

Response Objects

Responses are returned as structured Python objects rather than raw dictionaries.

Example:

status.subscription.plan

instead of:

status["subscription"]["plan"]

Benefits:

• IDE autocomplete
• Type safety
• Cleaner code

Error Handling

Example:

from api_sports import ApiSportsError

try:
    with ApiSportsClient(api_key="YOUR_API_KEY") as client:
        status = client.football.get_status()
except ApiSportsError as e:
    print(e)

Supported APIs

Currently supported:

• Football

Planned support:

• Basketball
• Baseball
• Hockey
• Handball

Development

Clone the repository:

git clone https://github.com/codeshard/pyapisports.git
cd pyapisports

Install dependencies:

uv sync --group dev

Run tests:

uv run pytest --cov --cov-branch

License

MIT License