Welcome to RiotWatcher’s documentation!

RiotWatcher is a thin wrapper on top of the Riot Games API for League of Legends. All public methods as of 7/4/2021 are supported in full.

RiotWatcher by default supports a naive rate limiter. This rate limiter will try to stop you from making too many requests, and in a single threaded test environment does this rather well. In a multithreaded environment, you may still get some 429 errors. 429 errors are currently NOT retried for you.

To Start…

To install RiotWatcher:

pip install riotwatcher


python setup.py install

You also need to have an API key from Riot. Get that from here.

Using it…

All methods return dictionaries representing the json objects described by the official Riot API. Any HTTP errors that are returned by the API are raised as HTTPError exceptions from the Requests library.

from riotwatcher import LolWatcher, ApiError

lol_watcher = LolWatcher('<your-api-key>')

my_region = 'na1'

me = lol_watcher.summoner.by_name(my_region, 'pseudonym117')

# all objects are returned (by default) as a dict
# lets see if i got diamond yet (i probably didnt)
my_ranked_stats = lol_watcher.league.by_summoner(my_region, me['id'])

# First we get the latest version of the game from data dragon
versions = lol_watcher.data_dragon.versions_for_region(my_region)
champions_version = versions['n']['champion']

# Lets get some champions
current_champ_list = lol_watcher.data_dragon.champions(champions_version)

# For Riot's API, the 404 status code indicates that the requested data wasn't found and
# should be expected to occur in normal operation, as in the case of a an
# invalid summoner name, match ID, etc.
# The 429 status code indicates that the user has sent too many requests
# in a given amount of time ("rate limiting").

    response = lol_watcher.summoner.by_name(my_region, 'this_is_probably_not_anyones_summoner_name')
except ApiError as err:
    if err.response.status_code == 429:
        print('We should retry in {} seconds.'.format(err.headers['Retry-After']))
        print('this retry-after is handled by default by the RiotWatcher library')
        print('future requests wait until the retry-after time passes')
    elif err.response.status_code == 404:
        print('Summoner with that ridiculous name not found.')


As of 7/4/2021, both the v4 and v5 versions of the Match API are supported by Riot. As such, RiotWatcher provides a method to use both. By default, the v4 API will be used for backwards compatibility.

To use the v5 API by default, use the following to initialize your LolWatcher instance:

from riotwatcher import LolWatcher

lol_watcher = LolWatcher('<your-api-key>', default_default_match_v5=True)

# example call
matchlist = lol_watcher.match.matchlist_by_puuid('AMERICAS', 'fake-puuid')

To explicitly use v4 or v5 during the deprecation period, you can use the following properties:

from riotwatcher import LolWatcher

lol_watcher = LolWatcher('<your-api-key>')

# use v5 explicitly
matchlist = lol_watcher.match_v5.matchlist_by_puuid('AMERICAS', 'fake-puuid')

# use v4 explicitly
old_matchlist = lol_watcher.match_v4.matchlist_by_account('na1', 'fake-account-id')

Note: this will not be supported after v4 is completely deprecated! Both match_v4 and match_v5 properties will be removed, and the change will happen with a minor version increase. If you desire seamless backwards compatibility, do not use these properies.

Use with kernel

RiotWatcher can integrate with the API proxy/caching server kernel. This can be done by providing the kernel_url parameter to the LolWatcher constructor.

from riotwatcher import LolWatcher, ApiError

lol_watcher = LolWatcher(kernel_url="https://your-kernel-instance") # should not contain trailing slash
# use watcher as normal

Indices and tables