league-sdk
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseLeague SDK
League SDK
Typed TypeScript SDK for Riot LoL API. Handles routing, PUUID conversions, rate limiting.
专为Riot LoL API打造的类型化TypeScript SDK,支持路由处理、PUUID转换及请求频率限制。
LoL API Concepts
LoL API 核心概念
Scope: This SDK covers League of Legends only. TFT, Valorant, Wild Rift have separate APIs.
PUUID: Universal ID across Riot games. Preferred over SummonerId/AccountId (deprecated).
Platform: Use player's server ( for Korean, for EU West). Wrong platform = 404.
kreuw1Queue IDs: Solo/Duo, Flex, ARAM, Normal Draft, Blind
420440450400430Timestamps: Unix epoch milliseconds →
new Date(match.gameCreation)Match history: Riot retains ~2 years. Older matches may be unavailable.
适用范围:本SDK仅覆盖《英雄联盟》。TFT、Valorant、Wild Rift拥有独立的API。
PUUID:Riot全游戏通用ID,优先级高于已弃用的SummonerId/AccountId。
平台区域:需使用玩家所在服务器(如韩国服为,西欧服为)。平台错误会返回404。
kreuw1队列ID: 单双排, 灵活组排, 极地大乱斗, 正常征召, 匹配模式
420440450400430时间戳:Unix时间戳毫秒值 → 可通过转换为日期对象
new Date(match.gameCreation)比赛历史:Riot仅保留约2年的比赛数据,更早的比赛可能无法查询。
Patterns
使用示例
typescript
import { LolClient, NotFoundError, RateLimitError } from 'league-sdk';
const client = new LolClient({
apiKey: process.env.RIOT_API_KEY!,
platform: 'na1'
});
// Player lookup
const player = await client.players.getByRiotId('Name', 'Tag');
// Ranked stats
const soloQ = await player.getSoloQueueStats();
// soloQ.tier, soloQ.division, soloQ.winRate (0-1 decimal)
// Match history
const matches = await player.getMatches({ count: 10, queue: 420 }); // 420 = ranked
for (const match of matches) {
const p = match.getParticipant(player.puuid)!;
console.log(`${p.championName} ${p.kills}/${p.deaths}/${p.assists} - ${p.win ? 'W' : 'L'}`);
}
// Participant stats
const p = match.getParticipant(player.puuid)!;
p.kills; p.deaths; p.assists; p.kda;
p.championName; p.win;
p.items; // { item0-5, trinket }
p.totalCs; p.csPerMinute;
p.damage.toChampions; p.damage.taken;
p.goldEarned; p.visionScore;
// Match stats
match.gameDurationFormatted; // "32:15"
match.queueName; // "Ranked Solo/Duo"
match.blueTeam; match.redTeam;
match.getWinner(); match.didPlayerWin(player.puuid);
// Team comparison
const { blueTeam, redTeam } = match;
console.log(`Blue: ${blueTeam.totalKills}K, ${blueTeam.totalGold}g`);
// Live game (null if not in game)
const game = await player.getLiveGame();
// Mastery
const top = await player.getTopMastery(3);
// m.championName, m.championPoints, m.championLevel
// Static data (no API key needed)
const champs = await client.dataDragon.getChampions();
const items = await client.dataDragon.getItems();
await client.dataDragon.getChampionIconUrl('Ahri');
await client.dataDragon.getItemIconUrl(3157);typescript
import { LolClient, NotFoundError, RateLimitError } from 'league-sdk';
const client = new LolClient({
apiKey: process.env.RIOT_API_KEY!,
platform: 'na1'
});
// 玩家查询
const player = await client.players.getByRiotId('Name', 'Tag');
// 排位数据
const soloQ = await player.getSoloQueueStats();
// soloQ.tier, soloQ.division, soloQ.winRate (0-1 小数形式)
// 比赛历史
const matches = await player.getMatches({ count: 10, queue: 420 }); // 420 = 单双排排位
for (const match of matches) {
const p = match.getParticipant(player.puuid)!;
console.log(`${p.championName} ${p.kills}/${p.deaths}/${p.assists} - ${p.win ? 'W' : 'L'}`);
}
// 参赛者数据
const p = match.getParticipant(player.puuid)!;
p.kills; p.deaths; p.assists; p.kda;
p.championName; p.win;
p.items; // { item0-5, trinket }
p.totalCs; p.csPerMinute;
p.damage.toChampions; p.damage.taken;
p.goldEarned; p.visionScore;
// 比赛数据
match.gameDurationFormatted; // "32:15"
match.queueName; // "Ranked Solo/Duo"
match.blueTeam; match.redTeam;
match.getWinner(); match.didPlayerWin(player.puuid);
// 队伍对比
const { blueTeam, redTeam } = match;
console.log(`Blue: ${blueTeam.totalKills}K, ${blueTeam.totalGold}g`);
// 实时游戏(未在游戏中则返回null)
const game = await player.getLiveGame();
// 英雄熟练度
const top = await player.getTopMastery(3);
// m.championName, m.championPoints, m.championLevel
// 静态数据(无需API密钥)
const champs = await client.dataDragon.getChampions();
const items = await client.dataDragon.getItems();
await client.dataDragon.getChampionIconUrl('Ahri');
await client.dataDragon.getItemIconUrl(3157);Asset Downloads
资源下载
bash
npx league-sdk-assets --output ./assets --allProgrammatic:
import { downloadAllAssets } from 'league-sdk/scripts'bash
npx league-sdk-assets --output ./assets --all程序化调用:
import { downloadAllAssets } from 'league-sdk/scripts'Platforms
支持的平台区域
na1euw1eun1krjp1br1la1la2oc1tr1rusg2ph2th2tw2vn2na1euw1eun1krjp1br1la1la2oc1tr1rusg2ph2th2tw2vn2Troubleshooting
问题排查
- 401: API key expired (dev keys last 24h)
- 404: Wrong platform or player doesn't exist
- 429: Rate limited (SDK handles automatically)
- NotFoundError: Player/match doesn't exist
- RateLimitError: Has property (seconds)
retryAfter - AuthenticationError: Invalid API key
- 401:API密钥过期(开发密钥有效期为24小时)
- 404:平台区域错误或玩家不存在
- 429:请求频率超限(SDK会自动处理)
- NotFoundError:玩家/比赛不存在
- RateLimitError:包含属性(单位:秒)
retryAfter - AuthenticationError:API密钥无效