VLRdevAPI

FAQ

Frequently asked questions about VLRdevAPI.

Getting Started

VLRdevAPI is a Python SDK that provides a type-safe interface for fetching Valorant esports data from VLR.gg. It handles scraping, parsing, and data normalization so you can focus on building your application. See the documentation for full details.
No. VLRdevAPI works without any API key or authentication. Just pip install vlrdevapi and start making calls.
Python 3.11 or later. The library uses modern Python features including type hints and async support.
Install with pip: pip install vlrdevapi. Or with uv (recommended): uv add vlrdevapi. See the installation guide for more options.
You can experiment with VLRdevAPI in your browser using a Python notebook on Google Colab or similar platforms. Just run pip install vlrdevapi in a notebook cell and start exploring.
Yes. VLRdevAPI is pure Python and works on all major operating systems. It has been tested on Windows 10/11, macOS, and Ubuntu Linux.

Usage

Yes. The built-in client respects a default rate limit to avoid overloading VLR.gg. You can configure the rate limit and retry behavior when creating a VLRClient instance. See the API reference for configuration options.
Yes. Both module-level access (sync) and async client are supported. Use VLRClient with async with for concurrent data fetching. Check the guides for async examples.
VLRdevAPI covers five namespaces: matches (upcoming, live, completed), teams (info, roster, stats, placements), players (profiles, agents, teams, match history), events (stages, standings, teams, matches), and series (VODs, player stats, economy data, rounds). Browse the full API reference for details.
Yes. The library is used in production by RiftWatch and the community. It includes error handling, retry logic, rate limiting, and typed exceptions for reliable operation. See the getting started guide for best practices.
VLRdevAPI provides a typed exception hierarchy: NotFoundError, RateLimitError, RequestError, and more. Import from vlrdevapi.exceptions and handle them with standard try/except blocks.
List endpoints return paginated responses with .page, .total_pages, and .matches properties. Use page=2, return_all=True to fetch all pages automatically.
Some endpoints support optional parameters like date ranges and region filters. Check the API reference for each endpoint to see available query parameters.

Technical

The core dependency is Pydantic v2 for data modeling and validation. The async client uses httpx for HTTP requests.
VLRdevAPI abstracts away HTML parsing, rate limiting, and data normalization. It is faster, more reliable, and requires less code than scraping VLR.gg directly. Read the comparison post for a detailed breakdown.
Yes. Module-level access works directly in notebooks. Use import vlrdevapi and call methods synchronously.
Pass options to VLRClient(timeout=30, max_retries=5, rate_limit_per_minute=20) or set environment variables. Check the API reference for all options.
Yes. The client includes an LRU response cache with configurable TTL to reduce redundant requests. Disable or adjust caching by passing cache_ttl=0 to VLRClient.
The client raises a RequestError when it cannot reach VLR.gg. Configure retry logic to automatically retry on transient failures. Check the changelog for any known issues.
Absolutely. The library is open source on GitHub. Check the development setup guide in the docs to get started with local development.

Troubleshooting

Make sure you installed the package: pip list | findstr vlrdevapi (Windows) or pip list | grep vlrdevapi (macOS/Linux). If missing, run pip install --upgrade vlrdevapi. Check that you are using Python 3.11+.
Check that the parameters you are passing are valid. For example, some endpoints require specific date formats or team IDs. If you are filtering by region or tier, verify that the filter values match the expected format. See the API reference for exact parameter specifications.
Slow responses are usually due to rate limiting or network latency. Increase the rate limit on your VLRClient if you have permission, or reduce the frequency of your requests. The library includes retry logic and caching -- enable caching to avoid redundant calls. See the guides for performance tips.
Reduce the frequency of your requests or increase the rate_limit_per_minute setting on your VLRClient. The default limit is conservative to protect both your application and VLR.gg. Consider spreading requests across longer intervals or using the async client for concurrent fetching with built-in throttling.
Set the log level to DEBUG in your application. VLRdevAPI uses Python's standard logging module. Add import logging; logging.basicConfig(level=logging.DEBUG) to see detailed information about requests, responses, and caching behavior.
Data is fetched and cached at different times. There may be a brief delay between when data appears on VLR.gg and when it is available through the API. Clear your client cache or wait a few minutes and try again. If the discrepancy persists, open an issue on GitHub.

Comparison

VLRdevAPI is the only dedicated Python SDK for VLR.gg data. Unlike general-purpose scraping tools, it provides typed models, automatic normalization, built-in rate limiting, and a clean namespace structure. Other options include scraping VLR.gg directly or using third-party APIs that may require API keys or have usage limits.
For most projects, VLRdevAPI is faster to set up and more reliable than scraping. It handles markup changes, rate limiting, and data normalization automatically. Scraping gives you full control but requires ongoing maintenance. See the detailed comparison for a full breakdown.
Yes, for Valorant esports data. BeautifulSoup requires you to write and maintain CSS selectors for every data point, handle pagination manually, and build your own rate limiting and caching. VLRdevAPI gives you all of that out of the box with a clean Pythonic interface. Use BeautifulSoup if you need data from sources not covered by VLRdevAPI.
Yes. VLRdevAPI works with any Python web framework. Use the async client with FastAPI for non-blocking request handling, or the sync client with Django views. Both patterns are supported and documented in the guides.

Project

No. VLRdevAPI is an independent open-source project by RiftWatch. It is not affiliated with, endorsed by, or connected to Riot Games or VLR.gg.
VLRdevAPI is open source on GitHub. Contributions are welcome: bug reports, feature requests, and pull requests are all appreciated. See the contributing guide in the repository.
The docs section covers contributor guides (development setup, contributing) and the API reference. The standalone guides section contains step-by-step tutorials for using the library. The blog has news, updates, and comparisons.
Open an issue on the GitHub repository. Include the version you are using (check with vlrdevapi.__version__) and steps to reproduce.
The changelog tracks every release, feature, and fix in VLRdevAPI. It covers all versions with detailed section breakdowns.
Check the GitHub repository for community links and discussions. Issues and pull requests are the primary way to engage with the project.
Updates are published as needed when VLR.gg changes its markup or when new features are added. Follow the changelog and GitHub releases for update notifications.
Yes. VLRdevAPI is open source under the MIT license. You can use it in personal, academic, and commercial projects. See the LICENSE file on GitHub for full terms.