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
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
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
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
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
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, neverNone
- check withif 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
Related
Source
Data scraped from: https://www.vlr.gg/{series_id}