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¶