VLR.gg API

Unofficial REST API for Valorant Esports Data

Access live matches, team stats, player profiles, and tournament data from vlr.gg

Quick Start · API Endpoints · Documentation UI

---

Quick Start

# Install
npm install

# Run development server
npm run dev

# Build for production
npm run build && npm start

Server runs at http://localhost:3000

Docker

docker-compose up -d

---

Documentation UI

Open http://localhost:3000 in your browser for interactive API documentation with Try It functionality.

---

API Endpoints

Matches

Method	Endpoint	Description
GET	/api/matches	List matches (upcoming/live/completed)
GET	/api/matches/:matchId	Match details with maps & player stats

Query params for /api/matches:

• status - upcoming | live | completed (default: upcoming)
• page - Page number for completed matches

Teams

Method	Endpoint	Description
GET	/api/teams/:teamId	Team profile, roster, socials
GET	/api/teams/:teamId/stats	Map statistics & win rates
GET	/api/teams/:teamId/news	Team news articles
GET	/api/teams/:teamId/events	Tournament history & prizes
GET	/api/teams/:teamId/matches	Match history

Players

Method	Endpoint	Description
GET	/api/players/:playerId	Player profile & career stats

System

Method	Endpoint	Description
GET	/health	Health check

---

Example Response

GET /api/matches/542278

{
  "success": true,
  "data": {
    "id": "542278",
    "url": "https://www.vlr.gg/542278",
    "status": "completed",
    "event": "Valorant Champions 2025 Playoffs: Lower Round 3",
    "time": "2025-01-15T12:00:00.000Z",
    "team1": {
      "name": "DRX",
      "score": 2
    },
    "team2": {
      "name": "Paper Rex",
      "score": 0
    },
    "maps": {
      "format": "BO3",
      "veto": [
        { "team": "DRX", "action": "ban", "map": "Icebox" },
        { "team": "Paper Rex", "action": "pick", "map": "Ascent" }
      ],
      "list": [
        {
          "name": "Ascent",
          "team1Score": 15,
          "team2Score": 13,
          "winner": "DRX"
        },
        {
          "name": "Lotus",
          "team1Score": 13,
          "team2Score": 8,
          "winner": "DRX"
        }
      ]
    },
    "overallStats": {
      "team1Players": [...],
      "team2Players": [...]
    }
  },
  "meta": {
    "timestamp": "2025-01-15T12:00:00.000Z",
    "cached": false,
    "requestId": "abc-123"
  }
}

---

Features

• Fast - <10ms response time (cached)
• Rate Limited - 100 req/min per IP
• CORS Enabled - Works from any origin
• Smart Caching - Different TTL per data type
• Type Safe - Full TypeScript

Cache TTL

Data	TTL
Live matches	30s
Completed matches	5m
Team profiles	1h
Team stats	30m
Player profiles	1h

---

Configuration

PORT=3000
HOST=0.0.0.0
NODE_ENV=production
LOG_LEVEL=info

---

Tech Stack

• Runtime: Node.js
• Framework: Fastify
• Language: TypeScript
• Scraping: Cheerio
• Caching: node-cache

---

Disclaimer

This is an unofficial API for educational purposes. All data belongs to vlr.gg.

Not affiliated with vlr.gg or Riot Games.

---

vlr.gg · Data source for Valorant esports