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).

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.

Using the spectator-v4 API
DarkIntaqt
DarkIntaqt
Published
Edited

©2020 - 2024

DarkIntaqt

DarkIntaqt

HomeAboutBlog