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.
- Helpful for personal projects, where you're only pulling stats for yourself and friends.
You can use the client in a couple of ways, but the recommended pattern is using the async with context manager. This ensures connections are properly closed and resources managed.
import asyncio
import os
# .. client declaration from above
async def main() -> None:
# Use environment variable for API key in actual code
real_key = os.environ.get("RIOT_API_KEY", "your_api_key")
# Re-instantiate with real key for the demo to run
async with NexarClient(riot_api_key=real_key, default_region=Region.NA1) as client:
print("Ready to make API calls!")
# ... do work here ...
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):
- 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:
# 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.division # RankDivision.IV, RankDivision.III, ...
solo_league_points = solo_rank.league_points
# Flex queue
flex_rank = await player.get_flex_rank()
# Of course, all of the same properties as Solo queue
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,
)
# 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)
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)
-
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.