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.

  • ValueErrorrankings is not “players”, “clubs”, or “brawlers”

  • ValueErrorlimit 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