v2.0.0
Initial release of VLRdevAPI. A type-safe Python SDK for Valorant esports data from VLR.gg.
Features
- Match listings: live matches, upcoming with pagination (`matches.upcoming(page=2, return_all=True)`), completed with date filtering.
- Team data: info (name, tag, socials), roster with roles/captain/sub status, map stats with agent composition breakdowns, completed and upcoming matches, roster transactions, event placement history with prize winnings.
- Player profiles: basic info, current and past teams, agent usage stats (`30d`, `60d`, `90d`, `all`), match history with configurable limit, consolidated profile with top agents.
- Event/tournament coverage: list with tier/region/status filters, info (dates, prize pool, location), stages, teams, matches, standings.
- Series/match detail: full match overview (teams, scores, map veto, per-game breakdowns), VOD links (YouTube/Twitch), per-player performance stats with ratings, round-by-round data, economy analysis, kill matrices, advanced stats (aces, clutches, multi-kills).
API
- Synchronous VLRClient with context manager support and curried access pattern (`client.team(4568).roster()`).
- Module-level convenience access via `import vlrdevapi` with a lazy-initialized default client.
- Pydantic v2 models with full type hints, field descriptions, and validation across all endpoints.
- Typed exception hierarchy: VLRdevError, NotFoundError, RequestError, RateLimitError, ParsingError, ValidationError.
Infrastructure
- Automatic retry logic with configurable strategy (max retries, backoff factor, status codes).
- Rate limiting with configurable max requests per minute per namespace.
- LRU response caching with configurable TTL to reduce redundant requests.
- URL enrichment that automatically resolves team IDs and series info on match listings.
- Dependency management with uv for fast installs and reproducible builds.
- Supports Python 3.11 and later.
Documentation
- Official documentation site at https://vlrdevapi.pages.dev built with Next.js 16 and Fumadocs.
- API reference covering every namespace, method, parameter, and return type.
- Practical examples for events, matches, teams, players, and cross-namespace queries.
- Getting started guide, quickstart tutorial, and development setup guide.
- Doc validation scripts (check_mdx_examples.py) that verify syntax and live execution of code examples in CI.
- GitHub Actions workflow for automatic doc validation on pull requests.
- Comprehensive test suite with fixture-based offline tests and live integration tests.