object-oriented programming concepts.
This document will provide you with a basic understanding of the Riot Games API. It is designed to help you begin exploring and developing with the API as
quickly as possible. We can't wait to see what you make!
Registering for the Riot Games API
Before you can begin developing with the Riot Games API, you must sign in with your League of Legends account.
When you sign in, a developer portal account is created for you, which generates a development API key associated with your account. Your account will also allow you to communicate with our
team regarding your application and usage, and vice versa. For more information on API keys, see the API Keys documentation. Note that
every Riot Games API request requires an API key, so you will need to include your API key using the api_key parameter on each request.
Remember to replace <key> with your API key.
For more information and examples, try executing APIs on the API Reference page.
The quickest route to making awesome is to see the simplest example possible. The following cURL request loads RiotSchmick's basic summoner object in JSON.
curl --request GET 'https://na.api.pvp.net/api/lol/na/v1.4/summoner/by-name/RiotSchmick?api_key=<key>' --include
Remember to replace <key> with your API key.
If you don't have cURL, but still want to try this out, you can copy and paste the URL into your browser.
Keep in mind the following guidelines as you build and maintain your project. We ask that you do certain validations before making calls to the API.
Note that keys can be revoked or disabled, or your API rate limit lowered, if your key is making consistent invalid calls along these lines.
- Make sure that you are using the proper value of either region or platform for the given endpoint. Some endpoints take a region parameter and some take a platform ID. Use the values that each specific endpoints
expects. If you specify the wrong type of value, the call will return a 403.
- Don't make assumptions about what the value region and platform ID values are. Check the Regional Endpoints documentation and ensure you are
using the right values. For example, we get a lot of calls using OCE1 as a platform ID, but the correct value is OC1. If you specify an incorrect region or platform value, the call will return a 403.
- Make sure that you are using the proper DNS for the region you are trying to hit. We see a lot of people making calls with the wrong DNS for the region they are specifying in the path. For example:
https://eune.api.pvp.net/api/lol/na/v1.4/summoner/585897 - the EUNE proxy doesn't know anything about the NA region, so this call will return a 403. If you aren't sure which DNS to use for which endpoint and
region combination, then use the API reference page to test it. The reference page will display the proper DNS and path parameters to use for each endpoint and region.
- If you have a input field on your site or in your app that lets a user enter a summoner name to lookup, do not blindly pass that value along to the API without first doing some validation. Any request with
a name parameter that contains any characters that are not valid for a summoner name, even if they are URL encoded, will return a 403. The full set of allowed characters across Riot, Tencent, and Garena regions
includes any visible Unicode letter characters, digits (0-9), spaces, underscores, and periods. Other than that, no punctuation characters are allowed. Thus, the regular expression to use for validating summoner
names would be as follows.
You should be rejecting inputs that don't match this regular expression (i.e., that contain any punctuation characters other than periods, underscores, and spaces), rather than sending them to the API.
- Keep your project current. Sometimes endpoints are deprecated and removed. If your key continues calling the old endpoints after they go away, the requests will return a 403.
- Keep track of the errors you are receiving and audit them over time. Just because you weren't getting 4xx errors before doesn't mean you never will. As mentioned in the previous point, the endpoints can change
over time, and you need to keep your project in working order if you want to keep your API access.
- In general, any 4xx errors returned from our API are client side errors, which means that there is something wrong with your request. If you see any 4xx errors coming back from the API, then you need to change
something on your end to fix the issue. For more information about any 4xx errors you may be receiving, refer to our Response Codes documentation.
For more information on what rate limits are, why we use them, and how they affect your usage of the API, please see the Rate Limiting
The Riot Games API returns all data in valid JSON. A few programming languages include native support for JSON. For those that don’t, you can find a suitable library at
Note that our APIs return only non-empty values to save on bandwidth. Zero is considered an empty value, as well as empty strings, empty lists, and nulls. Any numeric field
that isn't returned can be assumed to be 0 (or null as you prefer). Any list field that isn't returned can be assumed to be an empty list or null. Any String field that isn't
returned can be assumed to be empty string or null.
We offer static seed data to help get you started.
- The seed data contains 1,000 ranked solo queue games, but no games from any other queue type.
- The seed data is split into 10 files named matches1.json through matches10.json.
- The seed data will be updated once a quarter or whenever the format of match/match history APIs change.
You can find the seed data in the following directory:
Great! Now What?
Signing in with your League of Legends account is the quickest way to begin making API requests. Otherwise, if you're curious about the APIs themselves, consider viewing the full API reference.
View Full API Reference