league-sdk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

League 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 (
kr
for Korean,
euw1
for EU West). Wrong platform = 404.
Queue IDs:
420
Solo/Duo,
440
Flex,
450
ARAM,
400
Normal Draft,
430
Blind
Timestamps: 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。
平台区域:需使用玩家所在服务器(如韩国服为
kr
,西欧服为
euw1
)。平台错误会返回404。
队列ID
420
单双排,
440
灵活组排,
450
极地大乱斗,
400
正常征召,
430
匹配模式
时间戳: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 --all
Programmatic:
import { downloadAllAssets } from 'league-sdk/scripts'
bash
npx league-sdk-assets --output ./assets --all
程序化调用:
import { downloadAllAssets } from 'league-sdk/scripts'

Platforms

支持的平台区域

na1
euw1
eun1
kr
jp1
br1
la1
la2
oc1
tr1
ru
sg2
ph2
th2
tw2
vn2
na1
euw1
eun1
kr
jp1
br1
la1
la2
oc1
tr1
ru
sg2
ph2
th2
tw2
vn2

Troubleshooting

问题排查

  • 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
    retryAfter
    property (seconds)
  • AuthenticationError: Invalid API key
  • 401:API密钥过期(开发密钥有效期为24小时)
  • 404:平台区域错误或玩家不存在
  • 429:请求频率超限(SDK会自动处理)
  • NotFoundError:玩家/比赛不存在
  • RateLimitError:包含
    retryAfter
    属性(单位:秒)
  • AuthenticationError:API密钥无效