Getting Started

VLRdevAPI is a Python library for fetching Valorant esports data from VLR.gg. It handles HTTP requests, HTML parsing, and data normalization so you can work with typed Python objects instead of raw markup.

Architecture OverviewCopy Anchor Link

The library offers two ways to access data:

• Module-level access - a lazy-initialized default client provides quick one-liners
• Explicit VLRClient - gives you full control over configuration, timeouts, and resource lifetime

Both approaches expose the same six namespaces:

PrerequisitesCopy Anchor Link

• Python 3.11 or higher - Check your version with python --version

InstallationCopy Anchor Link

uv add vlrdevapi

Or with pip:

pip install vlrdevapi

Usage PatternsCopy Anchor Link

import vlrdevapi

matches = vlrdevapi.matches.upcoming()
for match in matches.matches[:5]:
    t1 = match.team1.name if match.team1 else "TBD"
    t2 = match.team2.name if match.team2 else "TBD"
    print(f"{t1} vs {t2}")

from vlrdevapi import VLRClient

with VLRClient() as client:
  page = client.matches.upcoming()
  for match in page.matches[:5]:
      t1 = match.team1.name if match.team1 else "TBD"
      t2 = match.team2.name if match.team2 else "TBD"
      print(f"{t1} vs {t2}")

import vlrdevapi

team = vlrdevapi.team(2593)
info = team.info()
roster = team.roster()
print(f"{info.name} has {len(roster.players)} players")

Namespace ReferenceCopy Anchor Link

Each namespace has dedicated methods for different data types:

• matches.upcoming() / matches.live() / matches.completed() - match listings
• team(id) - team-specific data (roster, stats, matches, placements)
• player(id) - player-specific data (profile, agents, teams, matches)
• event(id) - event-specific data (info, stages, standings, teams)
• series(id) - series-specific data (info, VODs, player stats, economy)
• news(page) / news.article(article_id) - news listings and full articles

Data Science Exports & Tabular SerializationCopy Anchor Link

Every response model in VLRdevAPI includes built-in tabular export methods:

import vlrdevapi

# Fetch player stats and convert to pandas or polars
players = vlrdevapi.series(754737).players()

# Export directly to pandas DataFrame
df = players.to_df()
print(f"Exported {len(df)} player records to DataFrame")

# Or to native Polars DataFrame
pl_df = players.to_polars()

# Save to disk as CSV, Excel, Parquet, or JSON
players.to_csv("players_stats.csv")
players.to_excel("players_stats.xlsx")
players.to_parquet("players_stats.parquet")
players.to_json("players_stats.json")

Model Context Protocol (MCP) ServerCopy Anchor Link

Connect Claude Desktop, Cursor, or autonomous agents to live Valorant esports data using the built-in MCP server:

# Run via CLI
vlrdevapi-mcp

# Or zero-install with uvx
uvx --from "vlrdevapi[mcp]" vlrdevapi-mcp

Learn more in the MCP Server Reference.

Next StepsCopy Anchor Link

• Follow the Quick Start for a complete, runnable example
• Explore the full API reference
• Check the Contributing guide to get involved