VlrDevApi

series.matches()

Get detailed per-map statistics for a series

Signature

import vlrdevapi as vlr

result = vlr.series.matches(
    series_id: int,
    limit: int | None = None,
    timeout: float = 5.0
) -> list[MapPlayers]

Parameters

Prop

Type

Return Value

Type: list[MapPlayers]

Returns a list of map statistics with player performance data.

Prop

Type

PlayerStats fields:

Prop

Type

Examples

Get Map Statistics

Get map statistics
import vlrdevapi as vlr

# Get all maps for a series
maps = vlr.series.matches(series_id=511536)

for map_data in maps:
    print(f"\nMap: {map_data.map_name}")
    print(f"Players: {len(map_data.players)}")
    
    # Show team scores if available
    if map_data.teams:
        team1, team2 = map_data.teams
        print(f"Score: {team1.score}-{team2.score}")
        print(f"Winner: {team1.name if team1.is_winner else team2.name}")

Analyze Player Performance

Analyze player performance
import vlrdevapi as vlr

# Get map stats
maps = vlr.series.matches(series_id=511536, limit=1)

if maps:
    map_data = maps[0]
    print(f"=== {map_data.map_name} ===")
    
    # Sort players by ACS
    sorted_players = sorted(
        [p for p in map_data.players if p.acs is not None],
        key=lambda x: x.acs,
        reverse=True
    )
    
    print("\nTop performers:")
    for player in sorted_players[:5]:
        print(f"{player.name}: {player.acs} ACS")
        print(f"  K/D/A: {player.k}/{player.d}/{player.a}")
        print(f"  Rating: {player.r}")
        if player.agents:
            print(f"  Agent: {', '.join(player.agents)}")

View Round-by-Round Results

View round-by-round results
import vlrdevapi as vlr

# Get map stats with rounds
maps = vlr.series.matches(series_id=511536)

for map_data in maps:
    if map_data.rounds:
        print(f"\n=== {map_data.map_name} - Round History ===")
        for round_result in map_data.rounds:
            winner = round_result.winner_team_short or "Unknown"
            method = round_result.method or "N/A"
            score = f"{round_result.score[0]}-{round_result.score[1]}" if round_result.score else "N/A"
            print(f"Round {round_result.number}: {winner} wins ({method}) - Score: {score}")

Compare Team Performance

Compare team performance
import vlrdevapi as vlr

# Get all maps
maps = vlr.series.matches(series_id=511536)

for map_data in maps:
    if map_data.teams:
        team1, team2 = map_data.teams
        print(f"\n{map_data.map_name}:")
        print(f"  {team1.name}: {team1.score} rounds")
        print(f"    ATK: {team1.attacker_rounds}, DEF: {team1.defender_rounds}")
        print(f"  {team2.name}: {team2.score} rounds")
        print(f"    ATK: {team2.attacker_rounds}, DEF: {team2.defender_rounds}")

Get Aggregate Stats

Get aggregate stats
import vlrdevapi as vlr

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

# Find aggregate stats (game_id == "All")
aggregate = next((m for m in maps if m.game_id == "All"), None)

if aggregate:
    print("Series Aggregate Stats:")
    for player in aggregate.players:
        print(f"\n{player.name}:")
        print(f"  ACS: {player.acs}")
        print(f"  K/D/A: {player.k}/{player.d}/{player.a}")
        print(f"  Rating: {player.r}")

Error Handling

  • Network failures: Returns an empty list []
  • Invalid series ID: Returns an empty list []
  • No map data: Returns an empty list []

The function never raises exceptions, making it safe to use without try-catch blocks.

Tips

  • The players field is always a list, never None - check with if map_data.players:
  • All numeric stats can be None - check before using
  • The first map in results may be aggregate stats with game_id == "All"
  • Use teams to get map scores and side performance (attacker/defender rounds)
  • The rounds field contains detailed round-by-round results when available
  • Combine with series.info() to get match header and picks/bans

Source

Data scraped from: https://www.vlr.gg/{series_id}