Usage Examples

This page provides practical examples for common use cases with vlrdevapi.

Search Examples

Search Across All Types

import vlrdevapi as vlr

results = vlr.search.search("nrg")
print(f"Found {results.total_results} results")

for team in results.teams:
    status = "inactive" if team.is_inactive else "active"
    print(f"Team: {team.name} ({status}) - {team.country}")

for player in results.players:
    rn = f" ({player.real_name})" if player.real_name else ""
    print(f"Player: {player.ign}{rn} - {player.country}")

Type-Specific Searches

import vlrdevapi as vlr
# Search only players
players = vlr.search.search_players("tenz")

# Search only teams
teams = vlr.search.search_teams("sentinels")

# Search only events
events = vlr.search.search_events("champions")

Match Tracking Examples

Track Tournament Progress

Monitor an ongoing tournament:

import vlrdevapi as vlr

def track_tournament(event_id):
    # Get event info
    info = vlr.events.info(event_id=event_id)
    print(f"Tournament: {info.name}")
    print(f"Prize Pool: {info.prize}")
    print(f"Location: {info.location}")
    print()

    # Get all matches
    matches = vlr.events.matches(event_id=event_id)

    # Separate by status
    completed = [m for m in matches if m.status == "completed"]
    upcoming = [m for m in matches if m.status == "upcoming"]
    ongoing = [m for m in matches if m.status == "ongoing"]

    print(f"Completed: {len(completed)}")
    print(f"Upcoming: {len(upcoming)}")
    print(f"Ongoing: {len(ongoing)}")
    print()

    # Show recent results
    print("Recent Results:")
    for match in completed[:5]:
        t1, t2 = match.teams[0], match.teams[1]
        print(f"  {t1.name} vs {t2.name}")
        if t1.score is not None and t2.score is not None:
            print(f"    Score: {t1.score}-{t2.score}")

track_tournament(event_id=2498)

Live Match Monitor

Monitor live matches:

import vlrdevapi as vlr
import time

def monitor_live_matches(refresh_interval=60):
    while True:
        vlr.fetcher.clear_cache()
        live_matches = vlr.matches.live()

        if not live_matches:
            print("No live matches")
        else:
            print(f"{len(live_matches)} live match(es):")
            for match in live_matches:
                print(f"  {match.team1.name} vs {match.team2.name}")
                print(f"  Event: {match.event}")
                if match.team1.score is not None:
                    print(f"  Score: {match.team1.score}-{match.team2.score}")

        time.sleep(refresh_interval)

Player Analysis Examples

Player Performance Analysis

Analyze player performance across agents:

import vlrdevapi as vlr

def analyze_player(player_id, timespan="60d"):
    # Get profile
    profile = vlr.players.profile(player_id=player_id)
    print(f"Player: {profile.handle} ({profile.real_name})")
    print(f"Country: {profile.country}")

    # Get agent stats
    stats = vlr.players.agent_stats(player_id=player_id, timespan=timespan)
    stats_sorted = sorted(stats, key=lambda s: s.usage_count or 0, reverse=True)

    print(f"\nTop Agents (Past {timespan}):")
    for stat in stats_sorted[:5]:
        if stat.agent and stat.agent != "All":
            print(f"{stat.agent}: {stat.rating:.2f} rating, {stat.acs:.0f} ACS")

    # Get recent match record
    matches = vlr.players.matches(player_id=player_id, limit=10)
    wins = sum(1 for m in matches if m.result == "win")
    losses = sum(1 for m in matches if m.result == "loss")
    print(f"\nRecent Record: {wins}W - {losses}L")

    # Show recent matches with stage/phase info
    print("\nRecent Matches:")
    for match in matches[:5]:
        stage_info = f"{match.stage} {match.phase}" if match.phase else match.stage or "N/A"
        print(f"  {match.event} - {stage_info}: {match.result}")

analyze_player(player_id=4164)

Match Analysis Examples

Match Deep Dive

Get detailed statistics for a match:

import vlrdevapi as vlr

def match_deep_dive(match_id):
    # Get series info
    info = vlr.series.info(match_id=match_id)

    print(f"Match: {info.teams[0].name} vs {info.teams[1].name}")
    print(f"Event: {info.event} - {info.event_phase}")
    print(f"Final Score: {info.score[0]}-{info.score[1]}")
    print(f"Format: {info.best_of}")
    print()

    # Show picks and bans
    if info.picks:
        print("Map Picks:")
        for pick in info.picks:
            print(f"  {pick.team} picked {pick.map}")

    if info.bans:
        print("\nMap Bans:")
        for ban in info.bans:
            print(f"  {ban.team} banned {ban.map}")

    print()

    # Get detailed map stats
    maps = vlr.series.matches(series_id=match_id)

    for i, map_data in enumerate(maps, 1):
        print(f"\nMap {i}: {map_data.map_name}")

        if map_data.teams:
            team1, team2 = map_data.teams
            winner = team1.name if team1.is_winner else team2.name
            print(f"  {team1.name} {team1.score} - {team2.score} {team2.name}")
            print(f"  Winner: {winner}")

        # Top performers
        if map_data.players:
            sorted_players = sorted(
                map_data.players,
                key=lambda p: p.acs or 0,
                reverse=True
            )

            print(f"\n  Top Performers:")
            for player in sorted_players[:3]:
                print(f"    {player.name}: {player.acs} ACS, {player.k}/{player.d}/{player.a}")

match_deep_dive(match_id=530935)

Team Analysis Examples

Team Comparison

Compare two teams:

import vlrdevapi as vlr
from collections import defaultdict

def compare_teams_from_event(event_id, team1_name, team2_name):
    # Get event matches
    matches = vlr.events.matches(event_id=event_id)

    team_stats = defaultdict(lambda: {"wins": 0, "losses": 0, "maps_won": 0, "maps_lost": 0})

    for match in matches:
        if match.status != "completed":
            continue

        t1, t2 = match.teams[0], match.teams[1]

        # Check if our teams are in this match
        for team_name in [team1_name, team2_name]:
            if team_name.lower() in t1.name.lower():
                t1_score = t1.score or 0
                t2_score = t2.score or 0
                if t1_score > t2_score:
                    team_stats[team_name]["wins"] += 1
                else:
                    team_stats[team_name]["losses"] += 1
                team_stats[team_name]["maps_won"] += t1_score
                team_stats[team_name]["maps_lost"] += t2_score

            elif team_name.lower() in t2.name.lower():
                t1_score = t1.score or 0
                t2_score = t2.score or 0
                if t2_score > t1_score:
                    team_stats[team_name]["wins"] += 1
                else:
                    team_stats[team_name]["losses"] += 1
                team_stats[team_name]["maps_won"] += t2_score
                team_stats[team_name]["maps_lost"] += t1_score

    print(f"Team Comparison for Event {event_id}")
    print("=" * 50)

    for team_name in [team1_name, team2_name]:
        stats = team_stats[team_name]
        print(f"\n{team_name}:")
        print(f"  Match Record: {stats['wins']}W - {stats['losses']}L")
        print(f"  Map Record: {stats['maps_won']}W - {stats['maps_lost']}L")

        if stats['wins'] + stats['losses'] > 0:
            win_rate = stats['wins'] / (stats['wins'] + stats['losses']) * 100
            print(f"  Win Rate: {win_rate:.1f}%")

compare_teams_from_event(event_id=2498, team1_name="Team Liquid", team2_name="FNATIC")

Team Analysis and Tracking

Track team performance:

import vlrdevapi as vlr

def analyze_team(team_id):
    # Get team information
    info = vlr.teams.info(team_id=team_id)
    print(f"Team: {info.name} ({info.tag})")
    print(f"Country: {info.country}")
    print(f"Active: {info.is_active}")
    print()

    # Get current roster
    roster = vlr.teams.roster(team_id=team_id)
    print(f"Current Roster ({len(roster)} players):")
    for member in roster:
        print(f"  {member.ign} - {member.real_name or 'N/A'}")
        if member.role:
            print(f"    Role: {member.role}")
    print()

    # Get recent match results
    completed = vlr.teams.completed_matches(team_id=team_id, limit=5)
    print("Last 5 Matches:")
    for match in completed:
        result = f"{match.team1.score}-{match.team2.score}"
        print(f"  {match.team1.name} vs {match.team2.name}: {result}")
        print(f"    {match.tournament_name}")
    print()

    # Get upcoming matches
    upcoming = vlr.teams.upcoming_matches(team_id=team_id, limit=3)
    print(f"Next {len(upcoming)} Matches:")
    for match in upcoming:
        print(f"  {match.team1.name} vs {match.team2.name}")
        if match.match_datetime:
            print(f"    {match.tournament_name} - {match.match_datetime.strftime('%B %d, %Y at %I:%M %p')}")
        else:
            print(f"    {match.tournament_name}")
    print()

    # Get tournament placements
    placements = vlr.teams.placements(team_id=team_id)
    print(f"Tournament History ({len(placements)} events):")
    for placement in placements[:5]:  # Show top 5
        print(f"\n  {placement.event_name} ({placement.year})")
        for detail in placement.placements:
            print(f"    {detail.series}: {detail.place} - {detail.prize_money}")

analyze_team(team_id=799)

Team Roster History and Transactions

Track team roster changes over time:

import vlrdevapi as vlr

def roster_analysis(team_id):
    # Get all previous players with status
    players = vlr.teams.previous_players(team_id=team_id)

    # Group by status
    active = [p for p in players if p.status == "Active"]
    left = [p for p in players if p.status == "Left"]
    inactive = [p for p in players if p.status == "Inactive"]

    print(f"Roster Status Summary:")
    print(f"  Active: {len(active)}")
    print(f"  Left: {len(left)}")
    print(f"  Inactive: {len(inactive)}")
    print()

    # Show active players
    print("Current Active Players:")
    for player in active:
        print(f"  {player.ign} ({player.position})")
        print(f"    Joined: {player.join_date}")
        print(f"    Country: {player.country}")
    print()

    # Show recent departures
    print("Recent Departures:")
    for player in left[:5]:
        print(f"  {player.ign} ({player.position})")
        print(f"    Joined: {player.join_date}, Left: {player.leave_date}")
    print()

    # Get raw transactions
    txns = vlr.teams.transactions(team_id=team_id)

    # Analyze transaction patterns
    joins = [t for t in txns if t.action == "join"]
    leaves = [t for t in txns if t.action == "leave"]

    print(f"Transaction Summary:")
    print(f"  Total Joins: {len(joins)}")
    print(f"  Total Leaves: {len(leaves)}")
    print()

    # Show recent transactions
    print("Recent Transactions:")
    for txn in txns[:10]:
        print(f"  {txn.date}: {txn.ign} - {txn.action} ({txn.position})")

roster_analysis(team_id=1034)

Data Export Examples

Export to CSV

Export event data to CSV:

import vlrdevapi as vlr
import csv

def export_event_matches(event_id, filename="matches.csv"):
    matches = vlr.events.matches(event_id=event_id)

    with open(filename, 'w', newline='', encoding='utf-8') as f:
        writer = csv.writer(f)
        writer.writerow(['Team 1', 'Team 1 Country', 'Team 2', 'Team 2 Country', 'Score', 'Status'])

        for match in matches:
            t1, t2 = match.teams[0], match.teams[1]
            score = f"{t1.score}-{t2.score}" if t1.score is not None else "TBD"
            writer.writerow([
                t1.name,
                t1.country or "N/A",
                t2.name,
                t2.country or "N/A",
                score,
                match.status
            ])

    print(f"Exported {len(matches)} matches")

export_event_matches(event_id=2498)

Comprehensive Team Analysis

A full, multi-step example for analyzing a team end-to-end:

import vlrdevapi as vlr

# Comprehensive team analysis
team_id = 799  # Velocity Gaming

# Get team info
info = vlr.teams.info(team_id=team_id)
print(f"Team: {info.name} ({info.tag})")
print(f"Region: {info.country}")

# Get roster
roster = vlr.teams.roster(team_id=team_id)
print(f"\nRoster: {len(roster)} players")

# Get recent matches
recent = vlr.teams.completed_matches(team_id=team_id, limit=5)
print(f"\nLast 5 matches:")
for match in recent:
    result = f"{match.team1.score}-{match.team2.score}"
    print(f"  {match.team1.name} vs {match.team2.name}: {result}")
    if match.match_datetime:
        print(f"    Date: {match.match_datetime.strftime('%B %d, %Y')}")

# Get placements
placements = vlr.teams.placements(team_id=team_id)
print(f"\nTotal events participated: {len(placements)}")

# Show top 3 recent placements
for placement in placements[:3]:
    print(f"\n{placement.event_name} ({placement.year})")
    for detail in placement.placements:
        print(f"  {detail.series}: {detail.place} - {detail.prize_money}")

These examples demonstrate common patterns. Adapt them to your needs.