Getting a Player’s League Match History Using the Riot API in Python

Introduction to using the Riot API in Python Part 4, Getting a Player’s Match History

This is part 4 of a tutorial series where I walkthrough creating a mini project using the Riot API in Python.

Here is a link to the first part of the series if you want to go from the beginning: Using The Riot API with Python. Part 1, Defining our mini project and… | by TheConnoisseur | Sep, 2023 | Medium

Welcome to the 4th part of this small tutorial series on using the Riot API in Python.

We’re almost arriving at the end of our mini project, with just a few more things to do.

In this part, we’ll get a player’s match history using their puuid and learn how to analyse match data.

Getting a Player’s Match History

If you haven’t already, I highly recommend checking out the last part of the tutorial: Querying The Riot API with Python: A Simple Introduction | by TheConnoisseur | Sep, 2023 | Medium

All the concepts we learnt from that part will be relevant here.

From the last part, we learnt how to get a player’s profile information by querying the Riot API in Python.

To get their match history, we will be doing the exact same thing, but using this endpoint: Riot Developer Portal (riotgames.com), MATCH-V5.

Last time, we only had the option to pass in one required parameter when using the SUMMONER-V4 endpoint, but this time we have a lot more options when calling the API, using the MATCH-V5 endpoint:

As you can see, we are required to pass in a puuid but the rest of the parameters are optional. Feel free to customise these values as much as you want but we will be setting the count parameter to 20 for the remainder of the project.

Lets get into coding a function to call this API endpoint.

This process is very similar to what we did in the last part where we accessed player/summoner data, so I’ll skip over some of the smaller details.

Our function signature will look like this:

We include a descriptive function name and have 3 parameters:

• summoner_puuid, puuid of player we are getting match history of
• matches_count, how many match ids we are requesting
• region, optional parameter to specify what region our player is in. Will be set to default region if not passed in

Optionally, you can give the function a descriptive docstring. This is one Chat-GPT generated for me:

The main body of the function will look like this:

As you can see it has the same structure as the function we coded out in the last part:

• We format our request URL
• We make the request to the API
• We check for any errors along the way and report any that occur
• We return the JSON from our response object

If you require a deeper explanation of this function then check out the previous part in this tutorial series

This function will return a list of match ids, each of which can be used to access data on a specific match played.

The entire function, all together, will look like this:

def get_match_ids_by_summoner_puuid(summoner_puuid, matches_count, region=settings.DEFAULT_REGION):
    """
    Retrieve a list of match IDs for matches recently played by a summoner.

    Args:
        summoner_puuid (str): The PUUID (Player Universally Unique ID) of the summoner.
        matches_count (int): The number of match IDs to retrieve.
        region (str, optional): The region where the summoner is located. Defaults to the value in settings.DEFAULT_REGION.

    Returns:
        list or None: A list of match IDs if successful, None if an error occurs during the API request.

    Raises:
        requests.exceptions.RequestException: If there's an issue with the API request.

    Example:
        get_matches_by_summoner('sample_puuid', 10, 'na')
    """
    params = {
        'api_key': settings.API_KEY,
        'count': matches_count,
    }
    api_url = f"https://{region}.api.riotgames.com/lol/match/v5/matches/by-puuid/{summoner_puuid}/ids"
    try:
        response = requests.get(api_url, params=urlencode(params))
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Issue getting summoner match data from API: {e}')
        return None

Let’s write some code in our __main__.py file to test our new function out:

from helpers import get_summoner_info, get_match_ids_by_summoner_puuid

summoner_name = "Conoisseur"

summoner = get_summoner_info(summoner_name)
print(summoner)
print(summoner['name'])

summoner_match_ids = get_match_ids_by_summoner_puuid(summoner['puuid'], 20)
print(summoner_match_ids)

All this bit of code does is use the summoner puuid, obtained from the get_summoner_info function, and passes it into our newly created get_match_ids_by_summoner_puuid function, to get a list of match ids.

On a successful API call, this will return the ids of the last 20 matches our summoner has played.

The output of running this code will look like this:

{'id': 'hGqlM71dcf2ftm2-3cIo8kzQafLAiQkRRzXkICH6OlznpUzdpS79yid0pQ', 'accountId': 'gzQspn1TfngAEAVHCDs7lBfVd0lmXmE0GfpRx03r55C2BpTSRLBD8VhH', 'puuid': 'qJMwrXcOhpCXLgnKGJsGRr1Ks4TLc_Pq92LR1wIpHqvP_uOU9jLca3sDk7dUQ8mASPweplXVHrtVcQ', 'name': 'Conoisseur', 'profileIconId': 5973, 'revisionDate': 1694988978563, 'summonerLevel': 48}
Conoisseur
['EUW1_6597728340', 'EUW1_6597671624', 'EUW1_6597620600', 'EUW1_6597540069', 'EUW1_6597465216', 'EUW1_6597094857', 'EUW1_6597015780', 'EUW1_6596490497', 'EUW1_6596054765', 'EUW1_6595704552', 'EUW1_6595321845', 'EUW1_6595032307', 'EUW1_6594163836', 'EUW1_6594115186', 'EUW1_6594067868', 'EUW1_6593007789', 'EUW1_6592613658', 'EUW1_6592546425', 'EUW1_6592496670', 'EUW1_6592451477']

Process finished with exit code 0

Now let’s get into the interesting stuff, how we can use a match id to analyse match data

Analysing Match Data

All we have right now is a match id, which is pretty useless on it’s own, but luckily MATCH-V5 comes with an endpoint which can be used to return a lot of data on a match by it’s match id: Riot Developer Portal (riotgames.com)

When I say a lot of data, I really mean a lot of it. To the point where it would take way too long to talk about everything returned in the response in this article, so instead I’ll talk about the main structure of it and the bits of information we will need.

We are calculating the player’s win ratio from their last 20 games, so the data we want to access is what team the player was on and did they win.

Let’s make a request to the API:

The JSON response returned will look like this, note here I am viewing it in my web browser:

This response in particular is a whopping 3000 lines of JSON. Yeah, pretty big.

Don’t worry though, most of it we won’t be using in this mini project.

If you look at the screenshot, you can see that we have two variables at the top of the hierarchy:

• metadata, holds the match id and puuids of all participants in the match
• info, holds all information relating to what happened in the match itself, including what each player did in the match

The info variable contains a list called participants which holds data on what each individual player did in the match.

Each participant includes whether they were on the winning team on not. This is what we will use to determine if our player won the match or not.

But how do we know which participant is our player?

The order in which the participants are in the metadata variable is the same order they are in the info variable.

This means we can use our player’s puuid to find it’s index in the metadata participants variable, and it will be in the same index in the info participants variable.

Don’t worry if this sounds confusing. It’s one of those things where it sounds confusing on paper but in practise it’s not that bad.

So now we know how to check if a player is on the winning team, let’s code it out.

Coding Out a Function to Check if a Player Won or Lost a Game

Just like our other functions, we’ll start by choosing a descriptive function signature and send a request to the API:

We now have access to match data JSON in our match_data variable.

We know need to know which index our player is in the info variable of the JSON response:

We query the metadata field’s participants list to check that our player’s puuid is present, checking that they were in the match. We then get the index their puuid is in the participants list, which will be the same index they are in the info fields participants list.

Let’s use that index to get our player’s data in this match:

player_info holds all kinds of data about our player’s performance in this match like kills, deaths, assists, etc. But the field we are interested in is win, which returns if the player was on the winning team or not. We can simply return this and our function is complete.

The entire function:

def did_player_win_match(summoner_puuid, match_id, region=settings.DEFAULT_REGION):
    params = {
        'api_key': settings.API_KEY,
    }
    api_url = f"https://{region}.api.riotgames.com/lol/match/v5/matches/{match_id}"

    try:
        response = requests.get(api_url, params=urlencode(params))
        response.raise_for_status()
        match_data = response.json()
    except requests.exceptions.RequestException as e:
        print(f'Issue getting match data from match id from API: {e}')
        return None

    if summoner_puuid in match_data['metadata']['participants']:
        player_index = match_data['metadata']['participants'].index(summoner_puuid)
    else:
        return None

    player_info = match_data['info']['participants'][player_index]
    return player_info['win']

Let’s write some code to test this in our __main__.py file:

from helpers import get_summoner_info, get_match_ids_by_summoner_puuid,\
    did_player_win_match

summoner_name = "Conoisseur"

summoner = get_summoner_info(summoner_name)
print(summoner)
print(summoner['name'])

summoner_match_ids = get_match_ids_by_summoner_puuid(summoner['puuid'], 20)
print(summoner_match_ids)

win = did_player_win_match(summoner['puuid'],summoner_match_ids[0])
print(win)

This imports our newly made function into our __main__.py file and runs it using our example summoner and one of their recently played matches. It then prints the output: whether that summoner was on the winning team or not.

On running this code, the output will look like this:

{'id': 'hGqlM71dcf2ftm2-3cIo8kzQafLAiQkRRzXkICH6OlznpUzdpS79yid0pQ', 'accountId': 'gzQspn1TfngAEAVHCDs7lBfVd0lmXmE0GfpRx03r55C2BpTSRLBD8VhH', 'puuid': 'qJMwrXcOhpCXLgnKGJsGRr1Ks4TLc_Pq92LR1wIpHqvP_uOU9jLca3sDk7dUQ8mASPweplXVHrtVcQ', 'name': 'Conoisseur', 'profileIconId': 5973, 'revisionDate': 1695408014544, 'summonerLevel': 50}
Conoisseur
['EUW1_6603326975', 'EUW1_6603272132', 'EUW1_6603219671', 'EUW1_6603179562', 'EUW1_6603120780', 'EUW1_6602163381', 'EUW1_6601136289', 'EUW1_6601092521', 'EUW1_6601043435', 'EUW1_6600147486', 'EUW1_6599974662', 'EUW1_6599911141', 'EUW1_6599830493', 'EUW1_6599795012', 'EUW1_6599094064', 'EUW1_6599063830', 'EUW1_6599013736', 'EUW1_6598484399', 'EUW1_6598435598', 'EUW1_6598400476']
True

Nice! Now we have a list of match ids for our player and a way to check if they won a match.

In the next part, we’ll finish this mini project and tutorial series. We’ll talk about next steps you could make to extend this project and improvements that could be made on the current design.

Next Part: Calculating a League Player’s Win Percentage in Python | by TheConnoisseur | Oct, 2023 | Medium

Previous Part: Querying The Riot API with Python: A Simple Introduction | by TheConnoisseur | Sep, 2023 | Medium

Thanks for reading!
If you enjoyed this article then feel free to clap it and check out some of my other articles :)