VLR.GG Unofficial API

A modern, on-demand RESTful API to scrape and serve Valorant esports data from vlr.gg.

---

This project provides structured JSON data for matches, news, teams, players, and events, making it easy for developers to build their own applications on top of Valorant data without the hassle of scraping.

✨ Features

• On-Demand Scraping: Data is fetched from vlr.gg in real-time when an API request is made.
• Modern Tech Stack: Built with Python, FastAPI, and Pydantic for a robust and efficient API.
• Comprehensive Endpoints: Access a wide range of data, from match results to player stats.
• Async Architecture: Utilizes httpx and asyncio for non-blocking I/O operations.
• Easy Deployment: Designed for seamless deployment on serverless platforms like Vercel.
• Tested: Comes with a suite of tests using pytest to ensure reliability.

🚀 Technology Stack

• Backend: Python 3.12+
• Framework: FastAPI
• HTTP Client: httpx
• HTML Parsing: selectolax
• Testing: pytest, pytest-asyncio, respx
• Linting/Formatting: ruff
• Type Checking: mypy

API Endpoints

The base URL for all endpoints is /api.

Endpoint	Method	Description
/health	GET	Health check endpoint.
/news	GET	Fetches the latest news articles.
/matches	GET	Fetches upcoming, live, and completed matches.
/matches/{match_id}	GET	Fetches the details of a specific match.
/events	GET	Fetches a list of events.
/events/{event_id}	GET	Fetches the details of a specific event.
/player/{player_id}	GET	Fetches the details of a specific player.
/search	GET	Searches for players and teams.

For detailed information on query parameters and response models, please refer to the Docs served at /docs.

📦 Installation

1. Clone the repository:

   git clone https://github.com/metehansenyer/vlrgg-api.git
   cd vlrgg-api

2. Create a virtual environment and activate it:

   python3 -m venv venv
   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

3. Install the dependencies:

   # Production (runtime-only)
   pip install -r requirements.txt
   
   # Development (lint, type-check, tests)
   pip install -r requirements.txt -r requirements-dev.txt

4. Configure environment variables:

   cp .env.example .env
   # Edit .env with your preferred settings

🔧 Environment Variables

This project uses .env files for configuration. See .env.example for all available options.

Variable	Description	Default Value
API_TITLE	The title of the API	VLR.GG API
API_DESCRIPTION	API description text	Valorant esports data API scraped from vlr.gg
API_VERSION	API version	1.0.0
API_DEVELOPMENT	For log level	1.0.0
HOST	Server host	0.0.0.0
PORT	Server port	8000
DEBUG	Enable debug mode	False
VLR_BASE_URL	Base URL for VLR.GG	https://www.vlr.gg
HTTP_TIMEOUT	Timeout for HTTP requests (seconds)	10
REQUEST_MIN_DELAY	Min delay between outbound requests (seconds)	0.5
REQUEST_MAX_DELAY	Max delay between outbound requests (seconds)	2.0
MAX_CONCURRENT_REQUESTS	Max concurrent outbound HTTP requests	2
USER_AGENT	User-Agent header for scraping	See .env.example
ACCEPT	Accept header	text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
ACCEPT_LANGUAGE	Accept-Language header	en-US,en;q=0.5
DEFAULT_NEWS_COUNT	Default number of news items to return	10
MAX_NEWS_COUNT	Maximum allowed news items to return	50
SEARCH_NEWS_PAGE_LIMIT	Max pages to search in news endpoint	10
DEFAULT_MATCHES_COUNT	Default number of matches	10
MAX_MATCHES_COUNT	Max number of matches	50
DEFAULT_PLAYER_MATCHES_COUNT	Default number of player matches	10
MAX_PLAYER_MATCHES_COUNT	Max number of player matches	50
DEFAULT_EVENTS_COUNT	Default number of events	10
MAX_EVENTS_COUNT	Max number of events	50
API_RATE_LIMIT_PER_MINUTE	Inbound API rate limit (per IP per minute)	60
CORS_ALLOW_ORIGINS	Comma-separated allowed origins for CORS	*
CORS_ALLOW_METHODS	Comma-separated allowed HTTP methods	GET
CORS_ALLOW_HEADERS	Comma-separated allowed headers	*
TRUST_PROXY	Trust X-Forwarded-For for client IP	False
RESPECT_ROBOTS	Respect robots.txt for outbound requests	True
ROBOTS_TTL_SECONDS	TTL for robots.txt cache	86400
STATIC_CACHE_SECONDS	Cache TTL for static assets	86400
DOCS_CACHE_SECONDS	Cache TTL for docs HTML	300
USE_SHARED_HTTP_SESSION	Shared HTTP session	False

🏃‍♂️ Running Locally

To start the local development server, run:

uvicorn main:app --reload

The API will be available at http://127.0.0.1:8000.

• Landing Page: http://127.0.0.1:8000
• Docs: http://127.0.0.1:8000/docs

✅ Testing

This project uses pytest for testing. To run the test suite:

pytest

🚀 Deployment

This API is designed to be easily deployed on serverless platforms like Vercel. The vercel.json file in the repository is configured for this purpose.

1. Push your code to a GitHub repository.
2. Create a new project on Vercel and connect it to your GitHub repository.
3. Vercel will automatically detect the FastAPI application and deploy it.

🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue if you have any suggestions or find any bugs.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a pull request.

🌐 Internationalization

• The site supports English and Turkish. Use the language switcher in the top navigation (EN | TR).
• To add a new language, drop a file at static/i18n/{lang}.json.
• The selected language is persisted in localStorage and reflected via the lang attribute on the <html> tag.

⚖️ Disclaimer

This project scrapes data from vlr.gg and is not affiliated with or endorsed by vlr.gg or Riot Games. Please use this API responsibly and respect the terms of service of the original website. The data provided is for educational and personal use only.

📄 License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.