Quick Start

The client

The primary object for Nexar is the NexarClient.

Here you set your Riot API key, pick a cache type (if any), and optionally set default regions(1) for your lookups.

1. Helpful for personal projects, where you're only pulling stats for yourself and friends.

StandardWith default regionsWith smart cache

from nexar.client import NexarClient

client = NexarClient(
    riot_api_key="your_api_key",
)

from nexar.client import NexarClient
from nexar.enums import Region

client = NexarClient(
    riot_api_key="your_api_key",
    default_region=Region.NA1,
)

from nexar.cache import SMART_CACHE_CONFIG
from nexar.client import NexarClient

client = NexarClient(
    riot_api_key="your_api_key",
    cache_config=SMART_CACHE_CONFIG,
)

You can use the client in a couple of ways, but the most common will be:

import asyncio

# .. client declaration from above


async def main() -> None:
    async with client:
        ...


if __name__ == "__main__":
    asyncio.run(main())

Note

All of the following examples will implicitly be done inside of this declared async with client context.

Snippets will also be de-indented for easier reading.

Player

The "heavylifter" model is Player. Player encapsulates multiple endpoints and allows you to elegantly make API calls and derive values without having to combine the output of many datapoints.

Read the full Player docs here

Getting players

To start, we either import Player and pass it our client, or use NexarClient.get_player().

from nexar.models import Player

# Get player with default region set in client
player = await client.get_player("bexli", "bex")
# or
player = await Player.by_riot_id(client, "bexli#bex")
# or
player = await Player.create(client, "bexli", "bex")

# Get a player from a different region
eu_player = await client.get_player(
    "Thebausffs",
    "COOL",
    region=Region.EUW1,
)

You can even get multiple Players at a time(1):

1. Though, they must be of the same region.

players = await client.get_players(["bexli#bex", "mltsimpleton#na1"])

# Iterate over players
for player in players:
    # Get player summoner info
    player_summoner = await player.get_summoner()
    # Print player summoner level
    print(f"{player.game_name} is level {player_summoner.summoner_level}")

Using Player

Player has quite a few convenience methods, like:

Current ranked standings

# Solo queue
solo_rank = await player.get_solo_rank()

if solo_rank:
    solo_tier = solo_rank.tier  # RankTier.Bronze, RankTier.Iron, ...
    solo_division = solo_rank.tier  # RankDivision.IV, RankDivision.III, ...
    solo_league_points = solo_rank.league_points

# Flex queue
solo_rank = await player.get_flex_rank()

# Of course, all of the same properties as Solo queue

Recent match history

from nexar.enums import Queue

# Get player's last match
last_match = await player.get_last_match()

# Get player's recent draft pick matches
last_10_draft_matches = await player.get_matches(
    count=10,
    queue=Queue.DRAFT_PICK,
)

Champion performance

# Get recent champion performance from matches
recent_champion = last_10_draft_matches.get_champion_stats()
if recent_champion:
    for stat in recent_champion:
        print(f"Average KDA with {stat.champion_name}: {stat.avg_kda:.2f}")
        # Output: (1)

1. Average KDA with Jinx: 2.91
   Average KDA with Jhin: 3.25
   Average KDA with Lillia: 2.09
   Average KDA with Warwick: 2.09
   Average KDA with Ashe: 2.50
   

Match

Another powerful model is Match, particularly in combination with Participant & ParticipantList.

last_match = await player.get_last_match()
assert last_match

start_time = last_match.info.game_start_timestamp
days_ago = (datetime.now(tz=UTC) - start_time).days
print(f"{player.game_name}'s last game was {days_ago} day(s) ago")

Participant

The difference between Player and Participant might be confusing.

A "participant" is 1 of 10 players (in a Summoner's Rift game, more or less for other modes). Attached to the Participant is all of the stats related to that player over the duration of the game.

participants = last_match.participants
winning_team = participants.winners()

winner_names = ", ".join([p.game_name or "Unknown" for p in winning_team])
print(f"Winners! {winner_names}\n")

for p in participants:
    name = p.game_name
    champ_name = p.champion_name
    kda = p.kda(as_str=True)
    print(f"{name} ({champ_name}) went {kda}")

# Output: (1)

1. Winners! Mojo Jo 77, Bravo, GAMr Guy, bexli, MltSimpleton
   
   FugginSuggin (Darius) went 2/9/1
   HeckenGena (Belveth) went 3/7/4
   Cauris (Annie) went 2/12/8
   SupremeKing (Jinx) went 14/7/4
   Villain King (Karma) went 2/6/10
   Mojo Jo 77 (Mordekaiser) went 12/4/3
   Bravo (Amumu) went 9/3/6
   GAMr Guy (Xerath) went 5/6/11
   bexli (Jhin) went 11/6/8
   MltSimpleton (Senna) went 4/4/19
   

ParticipantList

The easiest way to get a particular participant from a Match is using the very helpful ParticipantList, which is what is returned by Match.participants.

Get participant(s)

# Get participant by PUUID (easiest is from Player.puuid)
participant = participants.by_puuid(player.puuid)

# Get participants by position
from nexar.enums import MatchParticipantPosition as Position

bot_participants = participants.by_position(Position.BOTTOM)

# Get participants by champion (Not recommended, prone to typos)
jinx_players = participants.by_champion("Jinx")

Afterwhich we can dig into the stats

# Typical stats
magic_damage = participant.magic_damage_dealt_to_champions
cs = participant.creep_score
drags = participant.dragon_kills

# The really fun stuff
assert participant.challenges
buffs_stolen = participant.challenges.buffs_stolen
gold_per_min = participant.challenges.gold_per_minute

Get team

You can also easily get a particular team from a Match.

# Get blue team
blue_team = participants.blue_team()

# Get red team
red_team = participants.red_team()

# Get team of particular player
team_of_player = participants.team_of(player.puuid)