Getting League of Legends matches stats from the Riot API

It was a quiet summer night playing LoL with some friends. Suddenly I came up with an idea: “What if we play with all the champions of LoL and we cannot go to the next one until we won a game?”. Sounds cool but it’s not, believe me. With these innocent words we sentenced our lives to a decadence of early surrenders and humiliating defeats. After a deep silence, our developer souls raised the key question: “how can we automatize the track of this challenge?”. Well, that’s this post about: why playing with Riot’s API is even more fun than playing the game.

What do you need to start using the Riot API?

Surprisingly, the Riot API is really easy to access and if you are already a LoL player, you just need to use your account to access the Riot Developers Portal:

1. Go to https://developer.riotgames.com and login with your Riot’s account or create a new one.
2. In your dashboard, check your personal development API key. If it’s expired, just regenerate it from the button below. You will need this key to use the Riot API.
3. Explore the APIS and DOCS tabs to start learning how to use it.

Notice that a personal API key will expire in just one day! if you want to keep it fresh longer, you will need to register a product and wait until a Riot employee approves it. This is not a quick step, but you can start working in your prototype by using this personal key in the meantime.

Also beware that the current limitation of usage of the personal API is 20 requests every 1 seconds
and 100 requests every 2 minutes. Keep in mind when designing your proof of concept.

Performing a callout using the Riot API

Start by visiting the API tab from the developers portal. From there you will have the list of all the exposed endpoints you can perform a request. You can even test directly the API by using the “Execute Request” button:

Additionally we can see the headers and responses, so you can copy them and use it in your own code when performing a callout. As you can see from the above image, the API key should be included within the header as the “X-Riot-Token“. Don’t forget it or you will receive an error.

Accessing the data of one player using the Riot API

Before accessing the stats of the matches, we need to identify the player you want to query. As you may know, lot of stats in League of Legends are public including matches history, ranking, level and others. You can get a quick idea of how much information is public by searching a Summoner’s name or player nickname in sites like op.gg.

What is the PUUID?

The PUUID is a internal Riot identifier that will refer to a unique player. You will need this ID to keep using the rest of the API to query more data. You can obtain it by using the Summoner-V4, in my case I used this endpoint the /lol/summoner/v4/summoners/by-name/{summonerName} that will only use the summonerName as a parameter:

{
    "id": "4RyknKprLoQ1Dm08oq5xXjjFGq3NRfNsJS8qPR9rGoMOOuk",
    "accountId": "aso_-nrvsR3YdE0WMVx4AQM-1fq2r2KSd2Yp3lNwjlnXcY8",
    "puuid": "oTolk7oAhCqZSDx5yE5yVz3g4HSnUCkcRCYjtmL7gOwSjkEuhR5tt9A16acz4ga6Z2MUMb6_B3zCAQ",
    "name": "Faker",
    "profileIconId": 5212,
    "revisionDate": 1653508024000,
    "summonerLevel": 409
}

Get the PUUID from the response body and store it safely.

Retrieving the matches history using the Riot API

Match-V5 is all you need to retrieve the match history of a player. However you will need to perform two different callouts before accessing specific game stats:

• lol/match/v5/matches/by-puuid/{puuid}/ids: to retrieve a recent match IDs.

[
    "LA1_1255802252",
    "LA1_1254636149",
    "LA1_1254586345",
    "LA1_1254594040",
    "LA1_1253785975"
]

• lol/match/v5/matches/{matchId}: to access to all the stats of a single match.

"metadata": {...},
"info": {
    ...
    "participants": [{
         ...
         "championName": "Sivir",
         "win": false,
         ...
    }],
    ...
    }
}

This means that if you want to access the data of the last 20 matches, you will need to perform 1 callout for the first endpoint to receive the IDs and 20 callouts on the second endpoint using them.

In our case, we just wanted to know the champion the player used and if it won or lose. It sounds like a waste of resources performing all those callouts to get just a few stats. However, there is no other way of retrieving the match data as per the doc states.

Also check all the parameters you can use to filter our the list of the matches: startTime, endTime, count, … with a special mention of the Queue parameter.

What is the Queue ID parameter?

It identifies the type of match you want to retrieve. For example, if you only want to get normal 5vs5 from the draft mode, you will need to set the Queue ID to 400. You can check the list of all Queue IDs here.

Notice that you can use the Type parameter along the Queue ID to narrow down the list of matches you will get, those are mutually inclusive, so both conditions must match.

Code example

You can check a full example of retrieving some matches stats that we used to update automatically a Google Sheet every 24 hours. The code is implemented in JavaScript using some Google Script internal dependencies to perform the callouts and update a Google Sheet:

https://github.com/amolinasalazar/LOLAZChallenge

Hope this short tutorial gives you a good start to building awesome Riot apps. You can share in the comments all the ideas and prototypes you are working on. GL&HF!