Features

This page covers ValoPy’s core features and how to use them effectively.

Key Features

🚀 Async/Await - Built on asyncio for non-blocking operations
📦 Auto-parsing - Automatic JSON parsing into typed dataclass models
⏰ DateTime Parsing - ISO 8601 datetime strings automatically converted to Python datetime objects
🔄 Error Handling - Built-in exception classes for API errors
📚 Type Hints - Full type annotations for IDE support and static analysis

Using the Client

The Client class is the main entry point for all API interactions.

Context Manager (Recommended)

The recommended way to use the client is as an async context manager, which automatically handles session cleanup:

from valopy import Client

async def main():
    async with Client(api_key="your-api-key") as client:
        account = await client.get_account_v1("Name", "Tag")
        # Session is automatically closed when exiting the block

Manual Session Management

For more control, you can manage the session manually:

from valopy import Client

async def main():
    client = Client(api_key="your-api-key")
    try:
        account = await client.get_account_v1("Name", "Tag")
    finally:
        await client.close()  # Always close the session

Client Options

The client accepts these parameters:

client = Client(
    api_key="your-api-key",  # Required: Your API key
    redact_header=True,      # Optional: Redact API key in logs (default: True)
)

Available Methods

The client currently provides these methods:

Account Methods

Method	Description
`get_account_v1()`	Get account information by name and tag (V1)
`get_account_v1_by_puuid()`	Get account information by PUUID (V1)
`get_account_v2()`	Get account information by name and tag (V2) with additional fields like title and platforms
`get_account_v2_by_puuid()`	Get account information by PUUID (V2) with additional fields like title and platforms

Content Method

Method	Description
`get_content()`	Get game content including characters, maps, skins, sprays, and acts

Version Method

Method	Description
`get_version()`	Get current game version information for a specific region

Website Method

Method	Description
`get_website()`	Get website news articles for a specific country code

Status Methods

Method	Description
`get_status()`	Get server status including maintenances and incidents for a region

Queue Method

Method	Description
`get_queue_status()`	Get queue status and configurations for all game modes in a region

Esports Method

Method	Description
`get_esports_schedule()`	Get esports schedule with optional filtering by region and league

Leaderboard Method

Method	Description
`get_leaderboard()`	Get leaderboard for a region and platform with optional filtering and pagination

Method Parameters

Most methods support these common parameters:

force_update (bool) - Force fresh data instead of cached (default: False)
locale (Locale) - Language/region for localized content
region (Region) - Server region (EU, NA, LATAM, BR, AP, KR)
esports_region (EsportsRegion) - Esports region for filtering events
league (League) - Esports league for filtering events

Example usage:

from valopy import Client, Locale, Region

async with Client(api_key="your-api-key") as client:
    # Get content in Spanish
    content = await client.get_content(locale=Locale.ES_ES)

    # Get version for North America region
    version = await client.get_version(region=Region.NA)

    # Force update account data
    account = await client.get_account_v1("Name", "Tag", force_update=True)

For a complete list of all API endpoints (implemented and planned), see Supported Endpoints.

Automatic DateTime Parsing

ValoPy automatically converts datetime strings from the API into Python datetime.datetime objects. This happens transparently during deserialization, so you get native datetime objects in your models without any extra work.

The parser supports multiple datetime formats:

ISO 8601 - 2025-12-04T12:34:56Z or 2025-12-04T12:34:56+00:00
Date-only - 2025-12-04
Common format - Dec 4 2025 (used by some API responses)
Relative times - 3 minutes ago, 2 hours ago, 1 day ago, etc.

Any field that represents a timestamp in the API response is automatically parsed:

from valopy import Client
from datetime import datetime, timezone

async with Client(api_key="your-api-key") as client:
    leaderboard = await client.get_leaderboard(region=Region.NA, platform=Platform.PC)

    # updated_at is automatically a datetime object, not a string
    assert isinstance(leaderboard.updated_at, datetime)

    # You can use all datetime methods directly
    print(f"Updated: {leaderboard.updated_at.isoformat()}")
    print(f"Days ago: {(datetime.now(timezone.utc) - leaderboard.updated_at).days}")

    # Player updates are also parsed
    for player in leaderboard.players:
        print(f"{player.name}: Last updated {player.updated_at.strftime('%Y-%m-%d %H:%M:%S')}")

Fields that support automatic datetime parsing include:

Account timestamps (last_update, updated_at)
Version information (build_date, last_checked)
Status updates (created_at, updated_at, archive_at)
Esports events (date)
Leaderboard data (updated_at)
Website content (date)

Note: Relative time formats (like “3 minutes ago”) are converted to UTC datetime representing approximately when that time was, relative to the server’s current time.

Error Handling

ValoPy provides specific exception classes for different error scenarios:

from valopy import (
    Client,
    ValoPyNotFoundError,
    ValoPyPermissionError,
    ValoPyRateLimitError,
)

async with Client(api_key="your-api-key") as client:
    try:
        account = await client.get_account_v1("Name", "Tag")
    except ValoPyNotFoundError:
        print("Account not found")
    except ValoPyPermissionError:
        print("Invalid API key")
    except ValoPyRateLimitError as e:
        print(f"Rate limited, retry after {e.rate_reset}s")

See Exceptions for the complete exception hierarchy.