Part 1: What is the Riot Games API?
Last updated
Last updated
By the end of this article, we will have a good understanding of what the Riot Games API is, what data are available from it, and how you can retrieve this data.
The Riot Games API is a REST service (learn more about REST here) that Riot Games has provided to third-party developers (that’s us!) that provides data for us to use in our own applications and websites.
Some of the data that the Riot Games API provides:
Summoner details: name, level, profile icon, etc. (we will primarily be using this for the tutorial)
Match History and Match details and timelines
Whether or not someone is currently in a match
A lot more, check out the
is the best source of information on JSON, but a fairly simple explanation is that JSON is a data format that allows programs to pass data to each other (in this case between the Riot Games API and our website/server).
Your API key is exactly what you think a key would do, it “unlocks” access to the Riot Games API. It is a sequence of characters that you must include on every request to the API that “unlocks” the data and lets the API know that you have permission to access data from the API. Without it, the API won’t let you have any data. We’ll talk about this more as we begin using the API.
Note: Your API key is directly tied to your developer account and should be considered a secret value. This means never share your API key with anyone and never post it in a place where anyone else can access it. If somebody steals your key, they will be able to make requests that count against your rate limits and can possibly get your account blacklisted or banned (rate limits and blacklisting will be covered in later sections). If your key ever gets compromised, you can regenerate it here.
You should now see something that looks like this:
(The data will not be exactly the same, but it should look similar)
If you are getting an error that looks like
403 Forbidden, make sure that your API key is correct in the URL and has not expired.
The data is in the JSON format that I touched on earlier. We’ll get into more detail on how to use the data in Part 2, but for now just rejoice that you have successfully retrieved data from the API!
Lets briefly take a look at the different parts of the URL we just used:
https://- All requests to the API must use HTTPS. This ensures maximum security on your requests.
na1– This is the “Platform” that you’re making the request on. For example, NA summoners will use NA1, EUW summoners will use EUW1. See the Regional Endpoints page for more platform IDs. For now, just understand that a platform is related to the region that the summoner plays on
api.riotgames.com – This means we’re accessing the Riot Games API
lol/summoner/v3/summoners/by-name/– The API we're wanting data from, in this case summoners by name
WxWatch – the parameter for the endpoint, in this case, the name of the summoner we want data for (it's me!)
?api_key – Our API key which tells the API that we are allowed to get data
A more thorough breakdown of the API URLs will be covered in a later tutorial.
By now, you have learned what the Riot Games API is, the purpose and importance of your API key, and you have successfully retrieved your first bits of data from the API (and run into your first error message). In Part 2, we will apply everything we learned here as we start writing code to fetch and process the data from the API. Take as much time as you need to get an understanding of what was presented here, and we will see you in Part 2!
If you followed my advice and worked through the page, you’ve already made your developer account and likely have already made requests to the API, but we’ll pretend you didn’t and this is your very first call to the API. If you haven't, go do that now.
First, go fetch your API key from the – remember that the API won’t let you retrieve any data without your key – and keep it somewhere you can easily access it. Now we’re going make the simplest request to the API that we can do, using our browser. Go ahead and open up your browser and navigate to this webpage:
As you can see, we get an error message, specifically a401 Unauthorizederror. Remember our API key? We didn’t send it with our request, therefore, the API did not let us access any data. Let’s try it again, this time including our API key. Use this URL instead (be sure to replace with your API key):
An example with a fake API key would be:
The complete list of endpoints can be found . You can also use that link to play with the API and explore the different types of data you can retrieve. This series will focus only on Summoner-V3, but there are many others.