Using the spectator-v4 API
The spectator-v4 API is perfect to gather data about a live match in League of Legends. Be aware that the live data does not include CS, KDA or similar stuff from the current ongoing game.
The Response
{
"bannedChampions": [
{
"pickTurn": 1,
"championId": 266,
"teamId": 100
},
...
],
"gameId": "123456789",
"gameLength": 168,
"gameMode": "ARAM",
"gameQueueConfigId": 450,
"gameType": "MATCHED_GAME",
"mapId": 11,
"observers": {
"encryptionKey": "abu9202..."
},
"participants": [
{
"bot": false,
"championId": 45,
"perks":{
"perkIds": [
8128,
8143,
8138,
8106,
8014,
9111,
5008,
5008,
5002
],
"perkStyle": 8100,
"perkSubStyle": 8000
},
"profileIconId": 29,
"spell1Id": 4,
"spell2Id": 32,
"summonerName": "NAME",
"teamId": 100
},
...
],
"platformId": "EUW1"
}Fields (CurrentGameInfoDTO)
There are three DTOs within the initial respone, containing List[ParticipantDTO], List[BannedChampionDTO] and ObserverDTO. ParticipantDTO is not the same as in match v5.
| Field | Type | Note |
|---|---|---|
| bannedChampions | List[BannedChampionDTO] | Contains the information about all banned champions. |
| gameId | String (gameId) | Id of the game without the platform id. |
| gameLength | Number | Length of the game in seconds. Starting from 0:00. |
| gameMode | String (gameMode) | Gamemode type of the game. Usually "CLASSIC" or "ARAM". |
| gameQueueConfigId | Number (queueId) | QueueId of the gameMode. Useful to determine between. |
| gameType | String (gameType) | Type of the game. Not needed, if the gameQueueConfigId is given. |
| mapId | Number (mapId) | Id of the map currently playing on. 11 is Summoners Rift, 12 is Howling Abyss. |
| observers | ObserverDTO | Information about the observer, how to spectate a game. |
| participants | List[ParticipantDTO] | List of all summoners taking part in the game. |
| platformId | String (platformId) | Platform where the game is played. |
ParticipantDTO
The participantDTO has several intersting fields as well. Unfortunaly, stats like role, KDA or CS aren't included in the participantDTO.
| Field | Type | Note |
|---|---|---|
| teamId | Number | Id of the team. Team 100 is blue side and team 200 is red side. |
| spell1Id | Number | Id of the first summoner spell of the participant. |
| spell2Id | Number | Id of the second summoner spell of the participant. |
| championId | Number (championId) | Id of the champion the summoner is playing. |
| perks | PerkDTO | List of runes the summoner has equipped. |
| profileIconId | Number (profileIcon) | Id of the profile icon the summoner has selected. |
| bot | Boolean | Whether the summoner is a bot or not. |
| summonerName | String | Name of the summoner |
| summonerId | String (summonerId) | Also called "encrypted summoner id" or "summoner id". Id is unique per platform. |
| gameCustomizationObjects | List[] | Used to contain a summoners skins. Deprecated and currently empty. |
PerkDTO
Contains all the runes a summoner has equipped in the game.
| Field | Type | Note |
|---|---|---|
| perkIds | List[Number (perkId)] | Ids of the runes the summoners has selected. |
| perkStyle | Number (perkId) | Id of the primary tree of the summoners selected runes. |
| perkSubStyle | Number (perkId) | Id of the secondary tree of the summoners selected runes. |
Endpoints
There are two endpoints for the spectator-v4 API. One gets you the live-status of a requested summoner, the other endpoint is recommending you live-games to e.g. display on your site.
The base-url for the spectator-v4 API is the following:
https://{platform}.api.riotgames.com/lol/spectator/v4/
Please keep in mind to replace {platform} with your current platform.
By-Summoner
This endpoint gets your information about a specific summoner and their ingame status. The API returns a 404 - Not found status if the summoner is not ingame, don't get confused by that.
https://{platform}.api.riotgames.com/lol/spectator/v4/by-summoner/{encryptedSummonerId}
To execute this request, you need an encrypted summoner id using summoner-v4, so you might want to know how to get this first: Using the summoner-v4 API. The response is exactly as shown above (response heading).
Featured-Games
The featured-games endpoints returns (usually) several live games. The response is a list of the response shown above (response heading): List[CurrentGameInfoDTO].
{
"gameList": [
CurrentGameInfoDTO,
CurrentGameInfoDTO,
CurrentGameInfoDTO,
...
]
"clientRefreshInterval": 300
}The additional fields are the following:
| Field | Type | Note |
|---|---|---|
| gameList | List[CurrentGameInfoDTO] | Contains several featured live games. |
| clientRefreshInterval | Number | The suggested interval to wait before requesting FeaturedGames again. |
Using this path you can request the featured games.
https://{platform}.api.riotgames.com/lol/spectator/v4/featured-games
It is recommend to not call this page more often than recommend in "clientRefreshInterval", as the response isn't changing fast anyways and you can save up some API calls.
