vlrdevapi

The modern, type-safe Python library for VLR.gg Valorant esports data

Documentation · Quickstart · API Reference · Guides · Changelog · PyPI

vlrdevapi is a high-performance, type-safe Python client for extracting and analyzing Valorant esports data from VLR.gg. Built for competitive analysts, data scientists, Discord bot creators, and esports engineers, it delivers structured Pydantic models with full type hinting, built-in rate limiting, automatic retries, and comprehensive coverage across all VLR.gg entities.

Whether you need live match tickers, tournament brackets, historical player ratings, round-by-round economy buy matrices, or 2D minimap kill-feed replay timelines with player loadouts, vlrdevapi provides a clean, idiomatic interface.

Highlights

• Complete Valorant Esports Coverage — Tournaments, match schedules, live scoreboards, player careers, team rosters, roster transactions, and esports news.
• 2D Kill-Feed Replay Timelines — Spatial (x, y) kill coordinates, viewing angles, kill distances, plant/defuse events, spike detonations (boom), resurrections, alive player snapshots, and buy-phase player loadouts (weapons, shields, spent credits, remaining bank).
• Round-by-Round Economy — Full team buy matrices (loadout_value, spent, bank, buy classifications like Eco, Anti-eco, Semi-buy, Semi-rifle, and Full buy).
• Strictly Typed Pydantic Models — Every endpoint returns validated models with full field annotations, descriptive docstrings, and IDE autocompletion.
• Production-Ready Reliability — Built-in token-bucket rate limiter, exponential backoff retries, thread-safe connection pooling, and LRU-cached enrichment.
• Flexible Access Patterns — Use lightweight module-level calls (vlrdevapi.player.info(...)), curried ID chaining (vlrdevapi.player(11225).info()), or a managed context manager (with VLRClient() as client:).
• Timezone Awareness — Seamlessly convert match schedules and timestamps into any target timezone via Python's standard zoneinfo.
• Managed with uv — Blazing fast dependency resolution and testing workflows.

Installation

Install vlrdevapi using uv (recommended) or pip:

# Using uv (recommended)
uv add vlrdevapi

# Using pip
pip install vlrdevapi

Requirements: Python 3.11 or higher.

Quickstart

1. Direct Module-Level Access (Zero Setup)

Fetch data immediately without instantiating a client:

import vlrdevapi

# Get player profile and country
player = vlrdevapi.player.info(player_id=11225)
print(f"Player: {player.name} ({player.country})")

# Get series overview
series = vlrdevapi.series.info(series_id=542272)
print(f"Match: {series.team1.name} vs {series.team2.name} - Score: {series.score1}:{series.score2}")

# Get event details
event = vlrdevapi.event.info(event_id=2863)
print(f"Event: {event.name} ({event.start_date} to {event.end_date})")

2. Curried Method Chaining

Bind an ID once, then query multiple sub-methods without repeating the identifier:

import vlrdevapi

# Bind team 2593 (FNATIC) once
fnc = vlrdevapi.team(2593)

info = fnc.info()
print(f"{info.name} [{info.tag}] - Country: {info.country}")

roster = fnc.roster()
print(f"Active Players: {[p.ign for p in roster.players]}")

placements = fnc.placements()
print(f"Total Prize Earnings: {placements.total_winnings_currency}{placements.total_winnings:,}")

3. Managed Client Session (VLRClient)

For production applications, high-throughput scripts, or custom concurrency tuning, use VLRClient:

from vlrdevapi import VLRClient

with VLRClient(timeout=30, requests_per_second=8, max_retries=3) as client:
    # Live matches ticker
    live_matches = client.matches.live()
    for m in live_matches.matches:
        print(f"LIVE: {m.team1.name} vs {m.team2.name} ({m.event})")

    # Series performance & economy
    series = client.series(542272)
    econ = series.economy(game_id=1)
    print(f"Map 1 Rounds Analyzed: {len(econ.rounds)}")

API Overview & Reference

Code Examples

1. Spatial Replay Timeline & Round Loadouts

Inspect round-by-round kill events with 2D minimap locations, viewing angles, distances, and player equipment:

import vlrdevapi

# Fetch replay timeline for Game 3 of a series (Sunset)
replay = vlrdevapi.series.replay(series_id=754737, game_id=283288)
round_1 = replay.round(1)

if round_1:
    print(f"Round 1 Attacking Side: {round_1.attacking}")

    # Check buy-phase loadout for a player
    loadout = round_1.loadout_for("Derke")
    if loadout:
        print(f"Derke: Weapon={loadout.weapon}, Armor={loadout.armor}, Spent=${loadout.spent}")

    # Iterate through kill events
    for event in round_1.events:
        if event.type.value == "kill":
            killer = event.actor.name if event.actor else "World"
            victim = event.victim.name if event.victim else "Unknown"
            dist = f"{event.distance_units:.1f}u" if event.distance_units else "N/A"
            print(f"  [{event.clock}] {killer} killed {victim} with {event.cause} (dist: {dist})")
            if event.pos_x is not None:
                print(f"    Victim pos: ({event.pos_x}, {event.pos_y}) | Killer pos: ({event.from_x}, {event.from_y})")

Learn more in the Series Replay Documentation.

2. Round Economy & Team Buy Matrices

Analyze team spending, bank reserves, and buy types across rounds:

import vlrdevapi

economy = vlrdevapi.series.economy(series_id=754737, game_id=283288)

for r in economy.rounds[:5]:
    winner_name = r.winner.name if r.winner else "Unknown"
    print(f"Round {r.round_number}: Winner = {winner_name}")
    print(f"  {economy.team1}: {r.buy_type_team1} (Spent: ${r.spent_team1:,}, Bank: ${r.bank_team1:,})")
    print(f"  {economy.team2}: {r.buy_type_team2} (Spent: ${r.spent_team2:,}, Bank: ${r.bank_team2:,})")

Learn more in the Series Economy Documentation.

3. Player Career Statistics & Agent Pools

Extract ACS, K/D, KAST, and ADR broken down by agent:

import vlrdevapi

# Query player agent stats over the last 60 days
agent_stats = vlrdevapi.player.agents(player_id=11225, timespan="60d")

for a in agent_stats.agents[:4]:
    print(f"{a.agent:<10} | Pick Rate: {a.use} | Rating: {a.rating} | ACS: {a.acs} | K/D: {a.kd}")

Learn more in the Player Reference Documentation.

4. Tournament Brackets & Standings

Fetch event stages, match schedules, and final prize distributions:

import vlrdevapi

event_id = 2863  # e.g., Champions 2026
event = vlrdevapi.event(event_id)

# Event stages (Group Stage, Playoffs, etc.)
for stage in event.stages():
    print(f"Stage: {stage.name} (ID: {stage.id})")

# Final event standings & prize earnings
standings = event.standings()
for stage in standings.stages[:1]:
    print(f"--- {stage.stage_name} ---")
    for row in stage.standings[:3]:
        team_name = row.team.name if row.team else "TBD"
        prize = f"{row.prize_currency}{row.prize_money:,}" if row.prize_money else "N/A"
        print(f"  #{row.place}: {team_name} - Prize: {prize}")

Learn more in the Events Reference Documentation.

5. News Articles with Full Markdown

Read VLR.gg editorial content formatted in clean GitHub-flavored Markdown:

import vlrdevapi

# Get latest articles
feed = vlrdevapi.news(page=1)
latest = feed.news[0]

# Retrieve full article body
article = vlrdevapi.news.article(latest.id)
print(f"Title:  {article.title}")
print(f"Author: {article.author} ({article.date})")
print(f"Length: {len(article.content_md):,} characters")

Learn more in the News Reference Documentation.

Configuration & Error Handling

Rate Limiting & Concurrency

vlrdevapi includes sensible defaults (4.0 requests per second) to respect VLR.gg servers. When using VLRClient, you can customize client settings:

from zoneinfo import ZoneInfo
from vlrdevapi import VLRClient

client = VLRClient(
    timeout=20,                     # Timeout per request (seconds)
    requests_per_second=6,          # Max rate limit
    max_retries=4,                  # Exponential backoff retries
    source_tz=ZoneInfo("America/New_York"),  # Target timezone for schedules
)

Typed Exceptions

Catch errors with specific, typed exception classes from vlrdevapi.exceptions:

import vlrdevapi
from vlrdevapi.exceptions import (
    NotFoundError,
    RateLimitError,
    RequestError,
    ValidationError,
)

try:
    player = vlrdevapi.player.info(player_id=99999999)
except NotFoundError:
    print("Player not found on VLR.gg (404).")
except RateLimitError:
    print("Exceeded VLR.gg rate limits. Please slow down requests.")
except ValidationError as e:
    print(f"Invalid parameter passed: {e}")
except RequestError as e:
    print(f"Network error occurred: {e}")

Documentation & Guides

Comprehensive documentation, tutorials, and deep-dives are available on the official documentation portal:

• Documentation Home — Complete getting-started guide and architectural overview.
• Quickstart Guide — First queries in under two minutes.
• Series Replay Guide — Mapping 2D replay coordinates, viewing angles, and equipment.
• Series Economy Guide — Round spending and buy matrix mechanics.
• Guides & Tutorials — Real-world guides for Discord bots, Pandas analysis, and Polars pipelines.
• Frequently Asked Questions — Common questions on rate limits, IDs, and data structures.
• Changelog — Version history and release notes.

Development

Contributions and bug reports are welcome! This repository uses uv for package management and testing:

# 1. Clone the repository
git clone https://github.com/Vanshbordia/vlrdevapi.git
cd vlrdevapi

# 2. Install dependencies with uv
uv sync --group dev

# 3. Run the unit test suite
uv run pytest tests/ -v

# 4. Run static type checking and linter
uv run ruff check src/ tests/

Please read our Contributing Guide and Code of Conduct before submitting pull requests.

License

This project is licensed under the MIT License.

Disclaimer

vlrdevapi is an independent open-source library. It is not affiliated with, maintained, authorized, or endorsed by VLR.gg or Riot Games. Valorant and all associated properties are trademarks or registered trademarks of Riot Games, Inc. Please use responsibly and respect VLR.gg's bandwidth and server infrastructure.