API Reference

Client

class valorant.Client(key: str, locale: Optional[str] = Lex.LOCALE, region: str = 'na', route: str = 'americas', load_content: bool = True)

Represents a connection to the Riot Games API. Interacts specifically with VALORANT related endpoints.

A number of options can be passed to the Client.

Parameters
  • key (str) – An access key used to authenticate with the API. Depending on the key’s access level, match endpoints may be restricted.

  • locale (Optional[str]) – The region locale to use when making requests. This defaults to the system’s locale as determined by Python. (i.e locale.getdefaultlocale()) If set to None, ContentItemDTO.localizedNames will be included in the response.

  • region (Optional[str]) – The region to use when making requests. This defaults to na. Valid regions include na, eu, latam, etc. See Lex.REGIONS for a complete list of valid regions.

  • route (Optional[str]) – The region route to use when making requests for Riot Accounts. This defaults to americas. Valid routes are americas, asia, europe, and esports. See Lex.ROUTES for a complete list of valid routes.

  • load_content (bool) – Whether to load and cache content data from VALORANT upon initialization. Defaults to True.

Changed in version 1.0: Renamed reload parameter to load_content.

asset(**attributes: Mapping[str, Any]) Optional[Union[ActDTO, ContentItemDTO]]

Find an item in VALORANT content data matching all given attributes. Returns None if item is not found. This works because there are no semantic distinctions between Content Items.

For example, client.asset(name="Viper") would return a ContentItemDTO denoting content data for Viper.

Note

If content data is not cached, this function will make a request for it when called. Be wary of ratelimits should you decide not to cache content data.

Parameters

attributes (Mapping[str, Any]) – A mapping of keyword arguments to match for.

Return type

Optional[Union[ActDTO, ContentItemDTO]]

get_acts() List[ActDTO]

Get a ContentList of ActDTO objects from VALORANT.

Return type

ContentList[ActDTO]

get_characters() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent an Agent from VALORANT.

Return type

ContentList[ContentItemDTO]

get_charm_levels() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Gun Buddy Variant from VALORANT.

Return type

ContentList[ContentItemDTO]

get_charms() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Gun Buddy from VALORANT.

Return type

ContentList[ContentItemDTO]

get_chromas(strip: bool = False) List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Gun Skin or Gun Skin Color Variant from VALORANT.

Parameters

strip (bool) – If set to True, the \r\n and \n characters will be replaced by a single space character. This is useful for formatting the gun skin names.

Return type

ContentList[ContentItemDTO]

get_content(cache: bool = True) ContentDTO

Get complete content data from VALORANT.

Parameters

cache – If set to True, the Client will cache the response data, and subsequent calls wills return the cache. Update this cache by calling Client.get_content() again with cache set to True.

Note

The cache provided is stored in memory and will not persist across program restarts.

Return type

ContentDTO

get_current_act() Optional[ActDTO]

Helper function to get the current act from VALORANT. Returns None if the current act can’t be determined.

Return type

Optional[ActDTO]

get_equips() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent an Equippable items from from VALORANT (Includes abilities and standard guns/melee).

Return type

ContentList[ContentItemDTO]

get_game_modes() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Game Mode from VALORANT.

Return type

ContentList[ContentItemDTO]

get_leaderboard(size: int = 100, page: int = 0, pages: Optional[int] = None, actID: str = '') Union[LeaderboardDTO, LeaderboardIterator]

Get the ranked leaderboard for an Act in VALORANT.

Parameters
  • size (int) – Size of the leaderboard players to include. Can be between 1 and 100. If this value is greater than 100, the remaining items in leaderboard will be None.

  • page (Optional[int]) – Page of the leaderboard to retrieve. For example, page 4 of a leaderboard with a size of 50 will skip the first 200 players.

  • pages – Number of pages to retrieve from the leaderboard. If specified, the page parameter will be ignored. This will return a LeaderboardIterator of the retrieved pages.

  • actID (str) – ID of the Act to get the leaderboard from. This defaults to the currently active Act.

Examples:

# Get players from 101-200th rank on the leaderboard.
lb = client.get_leaderboard(size=100, page=2)
# Loop through multiple leaderboard pages.
pages = client.get_leaderboard(size=50, pages=3)

for page in pages:
    print(page.totalPlayers)

Note

The LeaderboardIterator will request the next page of the leaderboard after each iteration. Be wary of running into ratelimits when iterating over a large amount of pages.

Return type

Union[LeaderboardDTO, LeaderboardIterator]

get_maps() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Map from VALORANT.

Return type

ContentList[ContentItemDTO]

get_platform_status() PlatformDataDTO

Get status of VALORANT for the given platform.

Return type

PlatformDataDTO

get_player_cards() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Player Card from VALORANT.

Return type

ContentList[ContentItemDTO]

get_player_titles() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Player Title from VALORANT.

Return type

ContentList[ContentItemDTO]

get_skin_levels() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Gun Skin from VALORANT (Including levels, but not color variants).

Return type

ContentList[ContentItemDTO]

get_skins() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Gun Skin from VALORANT (Not including levels or color variants.)

Return type

ContentList[ContentItemDTO]

get_spray_levels() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Spray Variant from VALORANT.

Return type

ContentList[ContentItemDTO]

get_sprays() List[ContentItemDTO]

Get a ContentList of ContentItemDTO objects that each represent a Spray from VALORANT.

Return type

ContentList[ContentItemDTO]

get_user(puuid: str, route: str = 'americas') Optional[AccountDTO]

Get a Riot Account by their PUUID. Returns None if user could not be found.

Parameters
  • puuid (str) – The PUUID of the account to retrieve.

  • route (str) – Geographical route to get the account from. See Lex.ROUTES for a list of valid routes. Defaults americas.

Return type

Optional[AccountDTO]

get_user_by_name(name: str, route: str = 'americas') Optional[AccountDTO]

Gets a Riot Account by their game name and tag line. Returns None if user could not be found.

Parameters
  • name (str) – The account’s full game name and tag line, split by a hastag. (i.e frissyn#6969)

  • route (str) – Geographical route to get the account from. See Lex.ROUTES for a list of valid routes. Defaults americas.

Return type

Optional[AccountDTO]

LocalClient

class valorant.LocalClient(reigon='na')

Client for interacting with the local instance of the VALORANT application. This is called the RCS API. The game must be running for this class to function properly. Currently unstable, complete support is coming soon.

Warning

While interacting with the RCS API is not explicitly disallowed, please have some common sense. valorant.py is not liable for any punishment you may recieve if you break Riot’s Terms of Service. (i.e. creating an Auto Agent Selector)

Parameters

region (str) – The region to instance the client with. If this doesn’t match the game’s region there could be some unexpected behavior.

get_presences(user=False) dict

Get presence data for everyone connected to the player’s lobby. If the player is in a match, this will return session data for all players in a match. Same goes for queue, party, etc.

Parameters

user (bool) – If True, only returns presence data for the current player.

Return type

dict

get_session() dict

Get the current session of the player at the moment this function is called. Represents data for being in-queue, in-match, idle, etc.

Return type

dict

Expressions

valorant.exp(op: str, value: Any) Expression

Shorthand method for creating expressions to use alongside ContentList.get() or ContentList.get_all(). Expressions can also be created directly.

Parameters
  • op (Text) – The operator used to compare the element trait to the given value.

  • value (Any) – The value to compare the element trait to.

Return type

Expression

class valorant.Expression(op: str, value: Any)

Utility class for generating logical statements from a given operator and value. Supports object and logical operators. Also supports dot operators and member functions.

Parameters
  • op (Text) – The operator used to compare the element trait to the given value.

  • value (Any) – The value to compare the element trait to.

Note

The Expression class only supports logical and object comparisons, and cannot generate “flipped” statements. (i.e is not works, but not in doesn’t.)

statement(a: Any) bool

Executes the generated logical statement against the passed value.

Examples:

exp = valorant.Expression('>=', 50)
exp.statement(10) # => False
exp = valorant.Expression('.endswith', '!')
exp.statement("Hello, World!") # => True
Parameters

a (Any) – The value to test against.

Return type

bool

Lexicon

class valorant.Lex

Reference class for storing constants to be used across the library. Initializing isn’t allowed and will throw a NotImplementedError.

CLIENT_API = 'https://pd.{code}.a.pvp.net/'

URL for the Valorant client API.

CONTENT_NAMES = ['acts', 'characters', 'charmLevels', 'charms', 'chromas', 'equips', 'gameModes', 'maps', 'playerCards', 'playerTitles', 'skinLevels', 'skins', 'sprays']

List of content data attribute names.

ENDPOINTS = {'web': {'content': 'val/content/v1/contents', 'game-name': 'riot/account/v1/accounts/by-riot-id/{name}/{tag}', 'leaderboard': 'val/ranked/v1/leaderboards/by-act/{actID}', 'match': 'val/match/v1/matches/{matchID}', 'match-queue': 'val/match/v1/recent-matches/by-queue/{queue}', 'matchlists': 'val/match/v1/matchlists/by-puuid/{puuid}', 'puuid': 'riot/account/v1/accounts/by-puuid/{puuid}', 'status': 'val/status/v1/platform-data'}}

Mappings of endpoint names to endpoint paths for the client and web API.

HEADERS = {'web': {'Accept-Charset': 'application/x-www-form-urlencoded; charset=UTF-8'}}

Default headers for the client and web API.

LOCALE = 'en-US'

Default locale as determine by Python’s locale module.

LOCALES = ['ar-AE', 'de-DE', 'en-GB', 'en-US', 'es-ES', 'es-MX', 'fr-FR', 'id-ID', 'it-IT', 'ja-JP', 'ko-KR', 'pl-PL', 'pt-BR', 'ru-RU', 'th-TH', 'tr-TR', 'vi-VN', 'zh-CN', 'zh-TW']

List of locales supported by the client and web API.

RANKS = {0: 'Unrated', 1: 'Unused1', 2: 'Unused2', 3: 'Iron 1', 4: 'Iron 2', 5: 'Iron 3', 6: 'Bronze 1', 7: 'Bronze 2', 8: 'Bronze 3', 9: 'Silver 1', 10: 'Silver 2', 11: 'Silver 3', 12: 'Gold 1', 13: 'Gold 2', 14: 'Gold 3', 15: 'Platinum 1', 16: 'Platinum 2', 17: 'Platinum 3', 18: 'Diamond 1', 19: 'Diamond 2', 20: 'Diamond 3', 21: 'Ascendant 1', 22: 'Ascendant 2', 23: 'Ascendant 3', 24: 'Immortal 1', 25: 'Immortal 2', 26: 'Immortal 3', 27: 'Radiant'}

Mapping of competitiveTier values to rank title.

REGIONS = ['ap', 'br', 'eu', 'eune', 'euw', 'jp', 'kr', 'lan', 'las', 'latam', 'na', 'oce', 'ru', 'tr']

List of locales supported by the client and web API.

ROUTES = ['americas', 'asia', 'europe']

List of geographical routes supported by the Web API.

SAFES = "~()*!.'"

String of URL-safe characters in requests to the API.

WEB_API = 'https://{code}.api.riotgames.com/'

URL for the Valorant client API.

DTO

class valorant.DTO(obj: Mapping[str, Any])
dumps(**kwargs: Mapping) str

Converts the JSON representation of this DTO to a string.

Parameters

kwargs – Extra keyword arguments to build the string. Taks the same arguments as json.dumps.

Return type

str

json() dict

Return a JSON (dictionary) representation of this DTO.

Return type

dict

AbilityDTO

class valorant.AbilityDTO(obj: Mapping[str, Any])
ability1Effects: str
ability2Effects: str
grenadeEffects: str
ultimateEffects: str

AbilityCastsDTO

class valorant.AbilityCastsDTO(obj)
ability1Casts: int
ability2Casts: int
grenadeCasts: int
totalCasts: int
ultimateCasts: int

AccountDTO

class valorant.AccountDTO(obj, handle)
gameName: str
matchlist() MatchlistDTO

Get a MatchlistDTO of the most recent matches played by this account.

Return type

MatchlistDTO

puuid: str
tagLine: str

ActDTO

class valorant.ActDTO(obj: Mapping[str, Any])
id: str
isActive: bool
localizedNames: Mapping[str, str]
name: str

CoachDTO

class valorant.CoachDTO(obj: Mapping[str, Any])
puuid: str
teamId: str

ContentDTO

class valorant.ContentDTO(obj)
acts: List[valorant.objects.content.ActDTO]
characters: List[valorant.objects.content.ContentItemDTO]
charmLevels: List[valorant.objects.content.ContentItemDTO]
charms: List[valorant.objects.content.ContentItemDTO]
chromas: List[valorant.objects.content.ContentItemDTO]
equips: List[valorant.objects.content.ContentItemDTO]
gameModes: List[valorant.objects.content.ContentItemDTO]
maps: List[valorant.objects.content.ContentItemDTO]
playerCards: List[valorant.objects.content.ContentItemDTO]
playerTitles: List[valorant.objects.content.ContentItemDTO]
skinLevels: List[valorant.objects.content.ContentItemDTO]
skins: List[valorant.objects.content.ContentItemDTO]
sprayLevels: List[valorant.objects.content.ContentItemDTO]
sprays: List[valorant.objects.content.ContentItemDTO]
version: str

ContentItemDTO

class valorant.ContentItemDTO(obj)
assetName: str
assetPath: str
id: str
localizedNames: Optional[Mapping[str, str]]
name: str

ContentList

class valorant.ContentList(*args, **kwargs)
find(value: Optional[T] = None, **attrs: Mapping[str, T]) Optional[T]

Semantic alias for get().

find_all(value: Optional[T] = None, **attrs: Mapping[str, T]) Optional[T]

Semantic alias for get_all().

get(value: Optional[T] = None, **attrs: Mapping[str, T]) Optional[DTO]

Get the first element in the ContentList with traits that match all the keyword arguments passed in attrs. The arguments passed can be any value, an expression, or a callable that returns a boolean or boolean-like object.

A single argument defaults to checking for name.

Multiple arguments are checked using logical AND, not logical OR. The element must match all the arguments, not just one.

Returns None if no elements in the ContentList match the given arguments.

Examples:

agent = agents.get(name="Neon")
player = leaderboard.players.get(numberOfWins=lambda x: x >= 10)

See the Using Expressions and Queries page for more in-depth usage.

Parameters
  • value (Optional[Any]) – Alias argument for name=value. Ignores keyword arguments if passed.

  • attrs (Mapping[Any, Any]) – Mapping of attribute traits to match for.

Return type

Optional[DTO]

get_all(value: Optional[T] = None, **attrs: Mapping[str, T]) List[DTO]

Same functionality as get() but returns a list of every matching element. The list will be empty if no matching elements were found in the ContentList.

Parameters
  • value (Optional[Any]) – Alias argument for name=value. Ignores keyword arguments if passed.

  • attrs (Mapping[Any, Any]) – Mapping of attribute traits to match for.

Return type

List[DTO]

DamageDTO

class valorant.DamageDTO(obj: Mapping[str, Any])
bodyshots: int
damage: int
headshots: int
legshots: int
receiver: str

EconomyDTO

class valorant.EconomyDTO(obj: Mapping[str, Any])
armor: str
loadoutValue: int
remaining: int
spent: int
weapon: str

FinishingDamageDTO

class valorant.FinishingDamageDTO(obj: Mapping[str, Any])
damageItem: str
damageType: str
isSecondaryFireMode: bool

KillDTO

class valorant.KillDTO(obj)
assistants: List[str]
finishingDamage: valorant.objects.match.FinishingDamageDTO
killer: str
playerLocations: List[valorant.objects.player.PlayerLocationsDTO]
timeSinceGameStartMillis: int
timeSinceRoundStartMillis: int
victim: str
victimLocation: valorant.objects.player.LocationDTO

LeaderboardDTO

class valorant.LeaderboardDTO(obj)
actId: str
players: List[valorant.objects.ranked.LeaderboardPlayerDTO]
shard: str
totalPlayers: int

LeaderboardIterator

class valorant.LeaderboardIterator(caller: WebCaller, pages: int = 1, **params)

Simple iterator utility for getting multiple leaderboard pages. Each iteraction returns a LeaderboardDTO. See Client.get_leaderboard() for more info.

LeaderboardPlayerDTO

class valorant.LeaderboardPlayerDTO(obj)
gameName: Optional[str]
leaderboardRank: int
numberOfWins: int
puuid: Optional[str]
rankedRating: int
tagLine: Optional[str]

LocationDTO

class valorant.LocationDTO(obj: Mapping[str, Any])
x: int
y: int

MatchDTO

class valorant.MatchDTO(obj)
coaches: List[valorant.objects.match.CoachDTO]
matchInfo: valorant.objects.match.MatchInfoDTO
players: List[valorant.objects.player.PlayerDTO]
roundResults: List[valorant.objects.match.RoundResultDTO]
teams: List[valorant.objects.match.TeamDTO]
timestamp: datetime.datetime

MatchInfoDTO

class valorant.MatchInfoDTO(obj: Mapping[str, Any])
customGameName: str
gameLengthMillis: int
gameMode: str
gameStartMillis: int
isCompleted: bool
isRanked: bool
mapId: str
matchId: str
provisioningFlowId: str
queueId: str
seasonId: str

MatchlistDTO

class valorant.MatchlistDTO(obj, handle)
history: List[valorant.objects.match.MatchlistEntryDTO]
puuid: str

MatchlistEntryDTO

class valorant.MatchlistEntryDTO(obj, handle)
gameStartMillis: int
get() MatchDTO
matchId: str
teamId: str
timestamp() datetime

PlatformContentDTO

class valorant.PlatformContentDTO(obj: Mapping[str, Any])
content: str
locale: str

PlatformDataDTO

class valorant.PlatformDataDTO(obj)
id: str
incidents: List[valorant.objects.platform.StatusDTO]
locales: str
localizedNames: Mapping[str, str]
maintenances: List[valorant.objects.platform.StatusDTO]
name: str

PlayerDTO

class valorant.PlayerDTO(obj)
characterId: str
competitiveTier: int
gameName: str
partyId: str
playerCard: str
playerTitle: str
puuid: str
stats: Optional[valorant.objects.player.PlayerStatsDTO]
tagLine: str
teamId: str

PlayerLocationsDTO

class valorant.PlayerLocationsDTO(obj: Mapping[str, Any])
location: valorant.objects.player.LocationDTO
puuid: str
viewRadians: float

PlayerRoundStatsDTO

class valorant.PlayerRoundStatsDTO(obj)
ability: valorant.objects.match.AbilityDTO
damage: List[valorant.objects.match.DamageDTO]
economy: valorant.objects.match.EconomyDTO
kills: List[valorant.objects.match.KillDTO]
puuid: str
score: int

PlayerStatsDTO

class valorant.PlayerStatsDTO(obj)
abilityCasts: Optional[valorant.objects.player.AbilityCastsDTO]
assists: int
averageScore: Optional[int]
deaths: int
kd: Optional[int]
kda: Optional[int]
kills: int
playtimeMillis: int
roundsPlayed: int
score: int

RoundResultDTO

class valorant.RoundResultDTO(obj)
bombDefuser: str
bombPlanter: str
defuseLocation: valorant.objects.player.LocationDTO
defusePlayerLocations: Optional[List[valorant.objects.player.PlayerLocationsDTO]]
defuseRoundTime: int
plantLocation: valorant.objects.player.LocationDTO
plantPlayerLocations: Optional[List[valorant.objects.player.PlayerLocationsDTO]]
plantRoundTime: int
plantSite: Optional[str]
playerStats: List[valorant.objects.player.PlayerStatsDTO]
roundCeremony: str
roundNum: int
roundResult: str
roundResultCode: str
winningTeam: str

StatusDTO

class valorant.StatusDTO(obj)
archive_at: str
created_at: str
id: str
incident_severity: str
maintenance_status: str
platforms: List[str]
titles: List[valorant.objects.platform.PlatformContentDTO]
updated_at: str
updates: List[valorant.objects.platform.UpdateDTO]

TeamDTO

class valorant.TeamDTO(obj: Mapping[str, Any])
numPoints: int
roundsPlayed: int
roundsWon: int
teamId: str
won: bool

UpdateDTO

class valorant.UpdateDTO(obj)
author: str
created_at: str
id: str
publish: bool
publish_locations: List[str]
translations: List[valorant.objects.platform.PlatformContentDTO]
updated_at: str