Getting Started

Before proceeding with this introductory guide, we recommend becoming familiar with JavaScript Object Notation (JSON) and 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.

https://na.api.pvp.net/api/lol/na/v1.4/summoner/by-name/RiotSchmick?api_key=<key>

Remember to replace <key> with your API key.

For more information and examples, try executing APIs on the API Reference page.

Hello, World!

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.

Validating Calls

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.

  • 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.
    ^[0-9\\p{L} _\\.]+$
    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.
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.

Rate Limits

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

Response Formats

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 http://www.json.org.

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.

Seed Data

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 whenever changes are made to the match API.

You can find the seed data in our S3 bucket in AWS:
https://s3-us-west-1.amazonaws.com/riot-developer-portal/seed-data/

The directory itself is inaccessible, but the match files can be directly downloaded:
https://s3-us-west-1.amazonaws.com/riot-developer-portal/seed-data/matches1.json
https://s3-us-west-1.amazonaws.com/riot-developer-portal/seed-data/matches10.json

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.

Sign In View Full API Reference