Api Documentation

"All systems charged"

- Ezreal

Tournaments API

League of Legends custom games mode supports tournament codes that help players using the designated code to "fast track" into a private custom game lobby with preset game settings (map, pick type, etc). Each game played using a tournament code will have its results forwarded automatically (HTTP POST) to a URL specified by the tournament organizer. The Tournaments API helps tournament organizers generate tournament codes for their tournaments and ease the process of matchmaking and capturing end of game results.




The Tournaments API is a set of endpoints that provide developers with ability to:

  1. Register tournament providers and tournaments in a specific region/shard and its callback URL.
  2. Generate tournament codes for a given tournament.
  3. Receive game results in the form of an automatic callback (HTTP POST) from League of Legends servers whenever a game created using tournament code has completed.
  4. Use match identifier (matchID) received in the callback to pull full stats data for the given match.
  5. Pull end of game data based on given tournament code in case the callback is never received.
  6. Query pre-game lobby player activity events for a given tournament code.

Tournaments API Structure

The Tournaments API introduces a simple parent-child data structure to ensure data model consistency:




Tournaments API Methods

Access to the Tournaments API provides several new methods that can be viewed on the API Reference page. We suggest exploring every method to get more information on actual usage including the format and description of parameters you can supply.


APIMethodEndpointDescription
tournament-provider-v1      
  POST /tournament/public/v1/provider Create a new tournament provider for a given region
  POST /tournament/public/v1/tournament Create a tournament for a given provider
  POST /tournament/public/v1/code Create a tournament code for a given tournament
  PUT /tournament/public/v1/code/{tournamentCode} Update the pick type, map, spectator type, or allowed summoners for a given tournament code
  GET /tournament/public/v1/code/{tournamentCode} Fetch tournament code details for a given tournament code
  GET /tournament/public/v1/lobby/events/by-code/{tournamentCode} Fetch lobby events for a given tournament code
match-v2.2      
  GET /api/lol/{region}/v2.2/match/by-tournament/{tournamentCode}/ids Fetch match IDs for a given tournament code.
  GET /api/lol/{region}/v2.2/match/for-tournament/{matchId} Fetch match details for a given match ID and tournament code. Note that the DTOs returned by this endpoint and the standard match endpoint /api/lol/{region}/v2.2/match/{matchId} endpoint are the same. However, the standard match endpoint anonymizes summoner data for non-ranked games. The /api/lol/{region}/v2.2/match/for-tournament/{matchId} endpoint never anonymizes summoner data.

Full overview of all methods and their functionality is provided in the diagram below:




Best Practices

To preserve the quality of the tournaments service, your Tournaments API Key may be revoked if you do not adhere to the following best practices:

  • Respect the rate limit for your Tournament API Key and implement logic that considers the headers returned from a 429 Rate Limit Exceeded response, documented here.
  • Implement logic to detect unsuccessful API calls and back off accordingly. Please notify us if you believe your application is working correctly and you are receiving errors, but don't continue to slam the tournaments service with repeatedly unsuccessful calls.
  • Generate tournaments and tournament codes only as needed in production and development. Please don't create 1,000 tournament codes for a 10 game tournament. As a reminder, you can always create additional tournament codes as your tournament grows.
  • Tournaments and tournament codes should be generated within a reasonable time in relation to the event. Don't pre-create tournaments and tourmament codes at the start of the year and use them as the year progresses, but rather generate the tournament and codes as the event is announced and participants sign up.

Use Case Example

Presume there is a tournament website created for League of Legends players that does the following:

  • Announces tournament and rules
  • Registers players/teams
  • Generates/renders tournament brackets
  • Seeds registered teams across the brackets
  • Sends invites for matched teams to play their games
  • Collects end of game results from team captains
  • Provides new matches for teams that advance
  • Officiates for situations when something goes wrong (no show, etc)

The Tournaments API is designed to help automate the last four mentioned functions of tournament websites.

It is recommended to register a tournament provider (specifying region/shard and URL for results) well in advance and do a full loop testing to ensure everything is setup properly for your web service.


Generating Tournament Codes

To generate actual tournament codes follow the steps below:

  1. Use /tournament/public/v1/provider API endpoint to register as a provider in specific region while also setting a URL to be used for receiving game results notifications (HTTP POST). Returns providerID.
  2. Use providerID to register a tournament for given Tournament Provider. Receive tournamentID in return.
  3. Use tournamentID to generate one or more tournament codes for a given tournament using specified game settings (map, spectator rules, pick type etc).
    • A tournament code should only be used to create a single match. If you reuse a tournament code the server callback will not return stats for each match.
    • The method to generate tournament codes will return up to 1,000 tournament codes at a time. If needed, additional calls to this method can be made to create additional tournament codes.
    • Stale or unused tournament codes may be purged after a period of inactivity.

Tournament organizers can generate all the tournament codes they need in advance or generate them as necessary per each phase as shown below:




Server Callback

When a game created using tournament code has completed, the League of Legends servers will automatically make a callback to the tournament provider's registered URL via HTTP POST. Below are a couple notes about how the server callback works.

  • The callback from the League of Legends server relies on a successful response from the provider's registered URL. If a 200 response is not detected, there is a retry mechanism that will make additional attempts. In the rare occasion that a callback is not received within 5 minutes, you can assume the callback failed.
  • If you need to change your provider callback URL, you can register a new provider but remember tournaments generated with the old provider will continue to make callbacks to the old provider callback URL.
  • The callback mechanism requires the callback URL to be on port 80.

If you're having trouble debugging your logic, use the following cURL to mimic the behavior of the callback.

curl <callback_url> -X POST -H "Content-Type: application/json" -d '<response_body>'

Below is a sample JSON response returned by the League of Legends servers when a callback is made.

{
    "startTime": 1234567890000,
    "winningTeam": [
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        },
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        },
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        },
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        },
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        }
    ],
    "losingTeam": [
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        },
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        },
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        },
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        },
        {
            "summonerId": 12345678,
            "summonerName": "Summoner Name"
        }
    ],
    "shortCode": "NA1234a-1a23b456-a1b2-1abc-ab12-1234567890ab", //Tournament code
    "metaData": "{\"title\":\"Game 42 - Finals\"}", //Customizable field
    "gameId": 1234567890,
    "gameName": "a123bc45-ab1c-1a23-ab12-12345a67b89c",
    "gameType": "Practice",
    "gameMap": 11,
    "gameMode": "CLASSIC",
    "region": "NA1"
}

Lobby Events

In addition to game stats related methods, the lobby/events/by-code/{tournamentCode} method that can help query pre-game lobby events. This is useful for building tournament administration system and be able to detect whether a game for a given tournament code started normally. Below is an example of the JSON returned for lobby events:


{
    "eventList": [
        {
            "timestamp": "1234567890000",
            "eventType": "PracticeGameCreatedEvent", //Lobby Created
            "summonerId": "12345678"
        },
        {
            "timestamp": "1234567890000",
            "eventType": "PlayerJoinedGameEvent", //Player Joins Lobby
            "summonerId": "12345678"
        },
        {
            "timestamp": "1234567890000",
            "eventType": "PlayerSwitchedTeamEvent", //Player Switches Teams
            "summonerId": "12345678"
        },
        {
            "timestamp": "1234567890000",
            "eventType": "PlayerQuitGameEvent", //Player Leaves Lobby
            "summonerId": "12345678"
        },
        {
            "timestamp": "1234567890000",
            "eventType": "ChampSelectStartedEvent" //Champ Select Begins
        },
        {
            "timestamp": "1234567890000",
            "eventType": "GameAllocationStartedEvent" //Loading Screen Begins
        },
        {
            "timestamp": "1234567890000",
            "eventType": "GameAllocatedToLsmEvent" //Game Begins
        }
    ]
}