API Reference¶

Client¶

class brawlstats.Client(token, session=None, timeout=30, is_async=False, **options)[source]¶

A sync/async client class that lets you access the Brawl Stars API

Parameters:

token (str) – The API Key that you can get from https://developer.brawlstars.com
session (Union[requests.Session, aiohttp.ClientSession], optional) – Use a current session or a make new one, by default None
timeout (int, optional) – How long to wait in seconds before shutting down requests, by default 30
is_async (bool, optional) – Setting this to True makes the client async, by default False
loop (asyncio.AbstractEventLoop, optional) – The event loop to use for asynchronous operations, by default None. If you are passing in an aiohttp session, using this will not work: you must set it when initializing the session.
connector (aiohttp.BaseConnector, optional) – Pass a Connector into the client (aiohttp), by default None If you are passing in an aiohttp session, using this will not work: you must set it when initializing the session.
debug (bool, optional) – Whether or not to log info for debugging, by default False
base_url (str, optional) – Sets a different base URL to make request to, by default None

get_battle_logs(tag: bstag, use_cache=True) → BattleLog[source]¶

Gets a player’s battle logs.

Parameters:

tag (str) – A valid player tag. Valid characters: 0289PYLQGRJCUV
use_cache (bool, optional) – Whether to use the internal 3 minutes cache, by default True

Returns:

A player battle object with all of its attributes.

Return type:

BattleLog

get_brawlers(use_cache=True) → Brawlers[source]¶

Gets available brawlers and information about them.

Parameters:: use_cache (bool, optional) – Whether to use the internal 3 minutes cache, by default True
Returns:: A list of available brawlers and information about them.
Return type:: Brawlers

get_club(tag: bstag, use_cache=True) → Club[source]¶

Gets a club’s stats.

Parameters:

tag (str) – A valid club tag. Valid characters: 0289PYLQGRJCUV
use_cache (bool, optional) – Whether to use the internal 3 minutes cache, by default True

Returns:

A club object with all of its attributes.

Return type:

Club

get_club_members(tag: bstag, use_cache=True) → Members[source]¶

Gets the members of a club.

Parameters:

tag (str) – A valid club tag. Valid characters: 0289PYLQGRJCUV
use_cache (bool, optional) – Whether to use the internal 3 minutes cache, by default True

Returns:

A list of the members in a club.

Return type:

Members

get_event_rotation(use_cache=True) → EventRotation[source]¶

Gets the current events in rotation.

Parameters:: use_cache (bool, optional) – Whether to use the internal 3 minutes cache, by default True
Returns:: A list of the current events in rotation.
Return type:: Events

get_player(tag: bstag, use_cache=True) → Player[source]¶

Gets a player’s stats.

Parameters:

tag (str) – A valid player tag. Valid characters: 0289PYLQGRJCUV
use_cache (bool, optional) – Whether to use the internal 3 minutes cache, by default True

Returns:

A player object with all of its attributes.

Return type:

Player

get_profile(tag: bstag, use_cache=True) → Player¶

Gets a player’s stats.

Parameters:

tag (str) – A valid player tag. Valid characters: 0289PYLQGRJCUV
use_cache (bool, optional) – Whether to use the internal 3 minutes cache, by default True

Returns:

A player object with all of its attributes.

Return type:

Player

get_rankings(*, ranking: str, region: str | None = None, limit: int = 200, brawler: str | int | None = None, use_cache=True) → Ranking[source]¶

Gets the top count players/clubs/brawlers.

Parameters:

ranking (str) – The type of ranking. Must be “players”, “clubs”, “brawlers”.
region (str, optional) – The region to retrieve from. Must be a 2 letter country code, ‘global’, or None: by default None
limit (int, optional) – The number of top players or clubs to fetch, by default 200
brawler (Union[str, int], optional) – The brawler name or ID, by default None
use_cache (bool, optional) – Whether to use the internal 3 minutes cache, by default True

Returns:

A player or club ranking that contains a list of players or clubs.

Return type:

Ranking

Raises:

ValueError – The brawler name or ID is invalid.
ValueError – rankings is not “players”, “clubs”, or “brawlers”
ValueError – limit is not between 1 and 200, inclusive.

Data Models¶

class brawlstats.models.Player(*args, **kwargs)[source]¶

A player object with all of its attributes.

get_battle_logs() → BattleLog[source]¶

Gets the player’s battle logs.

Returns:: The battle log containing the player’s most recent battles.
Return type:: BattleLog

get_club() → Club[source]¶

Gets the player’s club.

Returns:: A list of the members in a club, or None if the player is not in a club.
Return type:: Club or None

class brawlstats.models.Club(client, data)[source]¶

A club object with all of its attributes.

get_members() → Members[source]¶

Gets the members of a club. Note: It is preferred to get the members via Club.members since this method makes an extra API call but returns the same data.

Returns:: A list of the members in a club.
Return type:: Members

class brawlstats.models.Ranking(client, data)[source]¶: A player or club ranking that contains a list of players or clubs.

class brawlstats.models.BattleLog(client, data)[source]¶: A player battle object with all of its attributes.

class brawlstats.models.Members(client, data)[source]¶: A list of the members in a club.

class brawlstats.models.Brawlers(client, data)[source]¶: A list of available brawlers and information about them.

class brawlstats.models.EventRotation(client, data)[source]¶: A list of events in the current rotation.

Attributes of Data Models¶

Note: These are subject to change at any time. Visit https://developer.brawlstars.com/#/documentation to view up-to-date information on the API.

Player¶

A full player object (all its statistics)

Attributes:

Name	Type
`tag`	str
`name`	str
`name_color`	str
`trophies`	int
`highest_trophies`	int
`power_play_points`	int
`highest_power_play_points`	int
`exp_level`	int
`exp_points`	int
`is_qualified_from_championship_challenge`	bool
`x3vs3_victories` / `team_victories`	int
`solo_victories`	int
`duo_victories`	int
`best_robo_rumble_time`	int
`best_time_as_big_brawler`	int
`brawlers`	List[PlayerBrawler]
`club.tag`	str
`club.name`	str
`icon.id`	int

Club¶

A full club object to get a club’s statistics. In order to get this, you must get it from the client or a player object.

Attributes:

Name	Type
`tag`	str
`name`	str
`description`	str
`type`	str
`trophies`	int
`required_trophies`	int
`members`	List[Member]
`badge_id`	int

Member¶

Members is a list of club members. Get this by accessing Club.members or Club.get_members(). The club’s members are sorted in order of descending trophies. Each Member in the list has the following attributes:

members = club.members
# Prints club's best player's name and role
print(members[0].name, members[0].role)

Attributes:

Name	Type
`tag`	str
`name`	str
`name_color`	str
`role`	str
`trophies`	int
`icon.id`	int

Ranking¶

A list of top players, clubs, or brawlers. Each item in the list has the following attributes:

Player/Brawler Ranking attributes:

Name	Type
`tag`	str
`name`	str
`name_color`	str
`trophies`	int
`rank`	int
`club.name`	str
`icon.id`	int

Club Ranking attributes:

Name	Type
`tag`	str
`name`	str
`trophies`	int
`rank`	int
`member_count`	int
`badge_id`	int

PlayerBrawler¶

PlayerBrawlers is a list of brawler objects, each with the following attributes. The brawlers are sorted in order of descending trophies. Note: PlayerBrawler only represents a brawler that a player owns and can only be accessed from Player.brawlers.

brawlers = player.brawlers
# List is sorted by descending trophies
top_brawler = brawlers[0]
# print the player's best brawler's name and trophies
print(top_brawler.name, top_brawler.trophies)

Attributes:

Name	Type
`id`	int
`name`	str
`power`	int
`rank`	int
`trophies`	int
`highest_trophies`	int
`star_powers`	List[StarPower]
`gadgets`	List[Gadget]
`gears`	List[Gear]

StarPower¶

Attributes:

Name	Type
`id`	int
`name`	str

Gadget¶

Attributes:

Name	Type
`id`	int
`name`	str

Gear¶

Attributes:

Name	Type
`id`	int
`name`	str
`level`	int

BattleLog¶

A BattleLog contains a list of items, each with the following attributes:

Attributes:

Name	Type
`battle_time`	str
`event`	Event
`battle`	List[Battle]

Event¶

An object containing information about an event.

Attributes:

Name	Type
`id`	int
`mode`	str
`map`	str

Battle¶

Each Battle object contains information about a battle. Note: The star_player attribute may not exist for certain modes that do not have a star player (e.g. showdown, duoShowdown).

Attributes:

Name	Type
`mode`	str
`type`	str
`result`	str
`duration`	int
`trophy_change`	int
`star_player`	BattlePlayer
`teams`	List[List[BattlePlayer]]

BattlePlayer¶

Represents a player who played in a battle.

Name	Type
`tag`	str
`name`	str
`brawler`	BattleBrawler

BattleBrawler¶

Represents a brawler that was played in a battle. Note: BattlerBrawler only reprents brawlers that were played in a battle and can only be accessed from BattlePlayer.brawler.

Name	Type
`id`	int
`name`	str
`power`	int
`trophies`	int

Brawlers¶

Represents a list of all brawlers in the game and information, with each item having the following attributes. Note: Brawlers only represents the brawler objects returned from Client.get_brawlers().

Attributes:

Name	Type
`id`	int
`name`	str
`star_powers`	List[StarPower]
`gadgets`	List[Gadget]

EventRotation¶

Represents a list of events in the current rotation, each with the following attributes:

Attributes:

Name	Type
`start_time`	str
`end_time`	str
`slot_id`	int
`event`	Event

API Reference¶

Client¶

Data Models¶

Attributes of Data Models¶

Player¶

Club¶

Member¶

Ranking¶

PlayerBrawler¶

StarPower¶

Gadget¶

Gear¶

BattleLog¶

Event¶

Battle¶

BattlePlayer¶

BattleBrawler¶

Brawlers¶

EventRotation¶

BrawlStats

Navigation

Related Topics