---

name: riot-api-reference description: | Riot Games API reference for League of Legends integration. Use when working with twisted library, API endpoints, rate limiting, PUUID lookups, match data, summoner info, or regional routing.

Riot Games API Reference

Comprehensive reference for integrating with the Riot Games API for League of Legends data.

API Endpoints Overview

Account-V1 (Riot ID Lookup)

Base URL: https://{region}.api.riotgames.com/riot/account/v1/

Important: Riot IDs replaced summoner names as of November 20, 2023. The by-name endpoints are deprecated.

Summoner-V4

Base URL: https://{platform}.api.riotgames.com/lol/summoner/v4/

Match-V5

Base URL: https://{region}.api.riotgames.com/lol/match/v5/

Query Parameters for matchlist:

• start - Start index (default 0)
• count - Number of matches (default 20, max 100)
• queue - Filter by queue ID
• type - Filter by match type (ranked, normal, etc.)
• startTime / endTime - Filter by timestamp (epoch seconds)

League-V4

Base URL: https://{platform}.api.riotgames.com/lol/league/v4/

Note: If a player hasn't finished placements or isn't ranked in a queue, that queue won't appear in results.

Champion-Mastery-V4

Base URL: https://{platform}.api.riotgames.com/lol/champion-mastery/v4/

Spectator-V5

Base URL: https://{platform}.api.riotgames.com/lol/spectator/v5/

Limitations: Stats like role, KDA, or CS are not included. Custom game data is not available due to privacy policies.

Challenges-V1

Base URL: https://{platform}.api.riotgames.com/lol/challenges/v1/

---

Regional vs Platform Routing

Platform Routing Values

Used for most endpoints (Summoner-V4, League-V4, Champion-Mastery-V4, Spectator-V5):

Regional Routing Values

Used for Account-V1 and Match-V5:

Example URLs:

CopyPlatform: https://na1.api.riotgames.com/lol/summoner/v4/summoners/by-puuid/{puuid}
Regional: https://americas.api.riotgames.com/lol/match/v5/matches/by-puuid/{puuid}/ids

---

Rate Limiting

Three Types of Rate Limits

1. Application Rate Limit - Per API key, per region

   • Development keys: 20 requests/second, 100 requests/2 minutes
   • Production keys: Higher limits based on approval

2. Method Rate Limit - Per endpoint, per key, per region

   • Each endpoint has its own limit (e.g., match history may be more restricted)

3. Service Rate Limit - Per service, shared across all applications

   • Can cause 429 errors without X-Rate-Limit-Type header

Rate Limit Headers

Error Handling

Blacklisting: Repeated violations result in temporary blacklisting (escalating duration), eventually permanent.

---

PUUID and Riot ID

Identifier Types

Recommended Workflow

1. Get PUUID from Riot ID:

   CopyGET /riot/account/v1/accounts/by-riot-id/{gameName}/{tagLine}
   

2. Use PUUID for all subsequent calls:

   CopyGET /lol/match/v5/matches/by-puuid/{puuid}/ids
   GET /lol/summoner/v4/summoners/by-puuid/{puuid}
   

Note: PUUIDs are encrypted per project. A PUUID from your dev key won't work with your production key.

---

Data Dragon (Static Data)

Base URLs

• Versions: https://ddragon.leagueoflegends.com/api/versions.json
• Data: https://ddragon.leagueoflegends.com/cdn/{version}/data/{locale}/
• Images: https://ddragon.leagueoflegends.com/cdn/{version}/img/

Common Data Files

Example URLs

CopyChampions: https://ddragon.leagueoflegends.com/cdn/14.24.1/data/en_US/champion.json
Items: https://ddragon.leagueoflegends.com/cdn/14.24.1/data/en_US/item.json
Champion image: https://ddragon.leagueoflegends.com/cdn/14.24.1/img/champion/Ahri.png
Item image: https://ddragon.leagueoflegends.com/cdn/14.24.1/img/item/1001.png

Community Dragon

Data Dragon can be inaccurate (especially champion spell data). Use Community Dragon (cdragon) for more accurate data:

• https://raw.communitydragon.org/

---

Twisted Library Usage

This project uses the twisted npm package for Riot API calls.

Installation

Copynpm install twisted

Basic Setup

Copyimport { LolApi, RiotApi, TftApi } from 'twisted';

const riotApi = new RiotApi({ key: process.env.RIOT_API_KEY });
const lolApi = new LolApi({ key: process.env.RIOT_API_KEY });

Common Operations

Copy// Get PUUID from Riot ID
const account = await riotApi.Account.getByRiotId(
  gameName,
  tagLine,
  RegionGroups.AMERICAS
);

// Get summoner by PUUID
const summoner = await lolApi.Summoner.getByPUUID(
  puuid,
  Regions.AMERICA_NORTH
);

// Get match history
const matches = await lolApi.Match.list(
  puuid,
  RegionGroups.AMERICAS,
  { count: 20 }
);

// Get match details
const match = await lolApi.Match.get(
  matchId,
  RegionGroups.AMERICAS
);

// Get ranked data
const leagues = await lolApi.League.bySummoner(
  summonerId,
  Regions.AMERICA_NORTH
);

Configuration Options

Copyconst api = new LolApi({
  key: 'RGAPI-xxx',
  rateLimitRetry: true,        // Auto-retry on 429 (default: true)
  rateLimitRetryAttempts: 3,   // Max retries
  concurrency: 10,             // Max concurrent requests
  debug: {
    logTime: true,
    logUrls: true,
    logRatelimits: true,
  }
});

---

Sources

• Riot Developer Portal
• Rate Limiting Documentation
• Data Dragon
• Riot API Libraries Documentation
• HextechDocs - Rate Limiting
• DarkIntaqt Blog - Routing
• DarkIntaqt Blog - Summoner V4
• DarkIntaqt Blog - IDs
• Twisted NPM Package
• Twisted GitHub
• Riot Games DevRel - Summoner Names to Riot ID
• Riot Games DevRel - PUUIDs