vlrdevapi 1.0.0

The comprehensive Python library for VLR.gg Valorant esports data scraping - tournaments, matches, players, and statistics

vlrdevapi

The Python library for VLR.gg Valorant esports data scraping and API access.

vlrdevapi is a comprehensive, type-safe Python client library designed specifically for scraping and accessing Valorant esports data from VLR.gg. As there is no official VLR.gg API, this library provides a standardized, reliable, and efficient way to programmatically access tournament information, match data, player statistics, and more.

Why vlrdevapi?

vlrdevapi is the fastest and most complete solution for Valorant esports data extraction:

• Comprehensive Coverage: Events, matches, players, series, teams, and statistics
• Type-Safe: Full Pydantic models with automatic validation
• Production-Ready: Built-in retry logic, error handling, and rate limit protection
• Developer-Friendly: Intuitive API design with extensive documentation
• Well-Maintained: Active development with regular updates
• Open Source: MIT licensed, community-driven development

Key Features

Data Access

Feature	Description
Events API	List, filter, and access tournament/event data including schedules, prize pools, and standings
Matches API	Get upcoming, live, and completed match information with real-time scores
Players API	Access player profiles, statistics, match history, and agent performance data
Series API	Detailed match analytics including map picks/bans, player stats, and round results

Technical Features

• Type Safety: Complete Pydantic model coverage with automatic validation
• Error Handling: Built-in retry logic with exponential backoff
• Rate Limiting: Automatic rate limit detection and handling
• Caching: Intelligent response caching to reduce API calls
• Fast Parsing: lxml-based HTML parsing for optimal performance
• Connection Pooling: Persistent HTTP connections for reduced latency

Installation

Requires Python 3.11 or higher.

pip install vlrdevapi

Development Installation

git clone https://github.com/vanshbordia/vlrdevapi.git
cd vlrdevapi
pip install -e .[dev]

Quick Start

import vlrdevapi as vlr

# List VCT events
events = vlr.events.list_events(tier="vct", status="ongoing")
for event in events:
    print(f"{event.name} - {event.status}")

# Get upcoming matches
matches = vlr.matches.upcoming(limit=5)
for match in matches:
    print(f"{match.teams[0]} vs {match.teams[1]} - {match.event}")

# Player profile and stats
profile = vlr.players.profile(player_id=4164)
print(f"{profile.handle} ({profile.real_name}) - {profile.country}")

agent_stats = vlr.players.agent_stats(player_id=4164, timespan="60d")
for stat in agent_stats:
    print(f"{stat.agent}: {stat.rating} rating, {stat.acs} ACS")

# Series information
info = vlr.series.info(match_id=530935)
print(f"{info.teams[0].name} vs {info.teams[1].name}")
print(f"Score: {info.score[0]}-{info.score[1]}")

Complete API Reference

Events Module - Tournament and Competition Data

import vlrdevapi as vlr

# List events with filters
events = vlr.events.list_events(
    tier="vct",           # "all", "vct", "vcl", "t3", "gc", "cg", "offseason"
    region="na",          # Optional region filter
    status="ongoing",     # "all", "upcoming", "ongoing", "completed"
    page=1
)

# Get event details
info = vlr.events.info(event_id=2498)

# Get event matches
matches = vlr.events.matches(event_id=2498)

# Get event standings
standings = vlr.events.standings(event_id=2498)

Matches Module - Match Schedules and Results

import vlrdevapi as vlr

# Upcoming matches
upcoming = vlr.matches.upcoming(limit=10)

# Live matches
live = vlr.matches.live()

# Completed matches
completed = vlr.matches.completed(limit=10, page=1)

Players Module - Player Information and Statistics

import vlrdevapi as vlr

# Player profile
profile = vlr.players.profile(player_id=4164)

# Player match history
matches = vlr.players.matches(player_id=4164, limit=20)

# Agent statistics
stats = vlr.players.agent_stats(
    player_id=4164,
    timespan="60d"  # "30d", "60d", "90d", "all"
)

Series Module - Detailed Match Analytics

import vlrdevapi as vlr

# Series/match information
info = vlr.series.info(match_id=530935)

# Detailed map statistics
maps = vlr.series.matches(series_id=530935)
for map_data in maps:
    print(f"Map: {map_data.map_name}")
    for player in map_data.players:
        print(f"  {player.name}: {player.k}/{player.d}/{player.a}")

Data Models and Type Safety

All API responses are returned as immutable Pydantic models with complete type hints:

Model	Purpose	Key Fields
ListEvent	Event list entries	id, name, status, dates, prize
Info	Detailed event data	name, prize, location, regions
Match	Match information	teams, score, event, status
Profile	Player profiles	handle, real_name, country, teams
AgentStats	Agent performance	agent, rating, acs, kd, kast
MapPlayers	Map statistics	map_name, players, teams, rounds

Model Features

• Immutable: All models are frozen after creation
• Validated: Automatic data validation using Pydantic
• Serializable: Easy conversion to dict/JSON
• Type-Hinted: Full IDE autocomplete support

# Access model fields
profile = vlr.players.profile(player_id=4164)
print(profile.handle)  # IDE autocomplete works

# Convert to dictionary
data = profile.model_dump()

# Serialize to JSON
json_str = profile.model_dump_json()

Use Cases

vlrdevapi is perfect for:

• Data Analysis: Build analytics dashboards and statistics trackers
• Betting Tools: Create prediction models and odds calculators
• Tournament Tracking: Monitor ongoing events and match results
• Player Scouting: Analyze player performance across agents and maps
• Content Creation: Generate automated match reports and summaries
• Discord Bots: Real-time match notifications and statistics
• Research: Academic studies on esports performance and trends

Advanced Usage

Pagination

Many functions support pagination for large datasets:

import vlrdevapi as vlr

# Get specific page
events = vlr.events.list_events(tier="vct", page=2)

# Limit results
matches = vlr.matches.upcoming(limit=20)

# Combine pagination with limits
results = vlr.matches.completed(limit=50, page=1)

Filtering

Filter data by multiple criteria:

# Filter events by tier and status
vct_events = vlr.events.list_events(
    tier="vct",
    region="na",
    status="ongoing"
)

# Filter player stats by timespan
recent_stats = vlr.players.agent_stats(
    player_id=4164,
    timespan="30d"  # Options: "30d", "60d", "90d", "all"
)

Cache Management

import vlrdevapi as vlr

# Clear cache for fresh data
vlr.fetcher.clear_cache()

# Close connections on shutdown
vlr.fetcher.close_connections()

Error Handling

The library raises specific exceptions for different error cases:

from vlrdevapi.exceptions import NetworkError, RateLimitError

try:
    events = vlr.events.list_events()
except RateLimitError:
    print("Rate limited by VLR.gg")
except NetworkError as e:
    print(f"Network error: {e}")

Testing

The library includes comprehensive tests with real HTML fixtures:

# Run all tests
pytest tests/lib/

# Run with coverage
pytest tests/lib/ --cov=vlrdevapi

# Run specific test module
pytest tests/lib/test_events.py -v

Documentation and Resources

Official Documentation

• Complete API Reference - Full function and model documentation
• Usage Examples - Practical code examples
• Data Models - Model schemas and validation
• Installation Guide - Setup and troubleshooting

Community and Support

• GitHub: github.com/vanshbordia/vlrdevapi
• Issues: Report bugs or request features
• Discussions: Community Q&A

Frequently Asked Questions

Is this an official VLR.gg API?

No. VLR.gg does not provide an official API. vlrdevapi is a community-maintained web scraping library that provides programmatic access to publicly available data on VLR.gg.

Is web scraping legal?

vlrdevapi only accesses publicly available data and respects VLR.gg's servers with built-in rate limiting, caching, and retry logic. Always use the library responsibly.

What Python versions are supported?

Python 3.11 and higher. The library uses modern Python features including type hints and pattern matching.

How do I get player/event IDs?

IDs can be found in VLR.gg URLs. For example, in https://www.vlr.gg/player/4164/aspas, the player ID is 4164.

Does it support other games?

No. vlrdevapi is specifically designed for Valorant esports data from VLR.gg.

Project Structure

vlrdevapi/
├── src/vlrdevapi/          # Source code
│   ├── events.py           # Events API
│   ├── matches.py          # Matches API
│   ├── players.py          # Players API
│   ├── series.py           # Series API
│   ├── fetcher.py          # HTTP client
│   ├── utils.py            # Parsing utilities
│   ├── exceptions.py       # Custom exceptions
│   └── constants.py        # Configuration
├── tests/                  # Test suite
│   ├── lib/                # Library tests
│   └── html_sources/       # HTML fixtures
├── docs/                   # Documentation
└── pyproject.toml          # Package configuration

Contributing

Contributions are welcome! Please ensure:

1. All tests pass: pytest tests/lib/
2. Code follows project style
3. New features include tests and documentation

License

Released under the MIT License. See LICENSE for details.

Disclaimer

This library scrapes data from VLR.gg. Please use responsibly and respect their terms of service. The library includes rate limiting protection and caching to minimize server load. vlrdevapi is not affiliated with or endorsed by VLR.gg or Riot Games.

Version

Current version: 1.0.0