Welcome to Brawl Stats’ documentation!¶

This library is a sync and async wrapper for the Brawl Stars API.
Python 3.5.3 or later is required.

Features¶

Easy to use with an object oriented design.
Use the same client for sync and async usage.
Get a player profile and battlelog.
Get a club and its members.
Get the top 200 rankings for players, clubs, or a specific brawler.
Get information about maps and more!
Get information about current available brawlers.

Installation¶

Install the latest stable build:

pip install brawlstats

API Reference¶

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

This is 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
timeout (Optional[int] = 30) – How long to wait in seconds before shutting down requests.
is_async (Optional[bool] = False) – Setting this to True makes the client async. Default is False
session (Optional[Union[requests.Session, aiohttp.ClientSession]] = None) – Use a current session or a make new one.
loop (Optional[asyncio.window_events._WindowsSelectorEventLoop]) – The event loop to use for asynchronous operations. Defaults to None, in which case the default event loop is asyncio.get_event_loop().
connector (Optional[aiohttp.TCPConnector]) – Pass a TCPConnector into the client (aiohttp). Defaults to None.
debug (Optional[bool] = False) – Whether or not to log info for debugging.
prevent_ratelimit (Optional[bool] = False) – Whether or not to wait between requests to prevent being ratelimited.
base_url (Optional[str] = None) – Sets a different base URL to make request to.

__ainit__()[source]¶: Task created to run get_brawlers asynchronously

get_battle_logs(tag: brawlstats.utils.bstag)[source]¶

Get a player’s battle logs.

Parameters:	tag (str) – A valid player tag. Valid characters: 0289PYLQGRJCUV BattleLog (Returns) –

get_brawlers()[source]¶

Get available brawlers and information about them.

No parameters

Returns Brawlers

get_club(tag: brawlstats.utils.bstag)[source]¶

Get a club’s stats.

Parameters:	tag (str) – A valid club tag. Valid characters: 0289PYLQGRJCUV Club (Returns) –

get_club_members(tag: brawlstats.utils.bstag)[source]¶

Get the members of a club.

Parameters:	tag (str) – A valid club tag. Valid characters: 0289PYLQGRJCUV Members (Returns) –

get_constants(key=None)[source]¶

Gets Brawl Stars constants extracted from the app.

Parameters:	key (Optional[str] = None) – Any key to get specific data. Constants (Returns) –

get_player(tag: brawlstats.utils.bstag)[source]¶

Get a player’s stats.

Parameters:	tag (str) – A valid player tag. Valid characters: 0289PYLQGRJCUV Player (Returns) –

get_profile(tag: brawlstats.utils.bstag)¶

Get a player’s stats.

Parameters:	tag (str) – A valid player tag. Valid characters: 0289PYLQGRJCUV Player (Returns) –

get_rankings(*, ranking: str, region=None, limit: int = 200, brawler=None)[source]¶

Get the top count players/clubs/brawlers.

Parameters:

ranking (str) – The type of ranking. Must be “players”, “clubs”, “brawlers”. Anything else will return a ValueError.
region (Optional[str]) – The region to retrieve from. Must be a 2 letter country code.
limit (Optional[int] = 200) – The number of top players or clubs to fetch. If count > 200, it will return a ValueError.
brawler (Optional[Union[str, int]] = None) – The brawler name or ID.
Ranking (Returns) –

Data Models¶

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

Returns a full player object with all of its attributes.

get_club()[source]¶

Gets the player’s club.

Returns Optional[Club]

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

Returns a full club object with all of its attributes.

get_members()[source]¶

Gets the members of a club.

Returns Members

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

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

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

class brawlstats.models.Constants(client, data)[source]¶: Returns some Brawl Stars constants.

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

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`	int
`team_victories`	int
`solo_victories`	int
`duo_victories`	int
`best_robo_rumble_time`	int
`best_time_as_big_brawler`	int
`club.tag`	str
`club.name`	str
`brawlers`	List[Brawler]

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]

Members¶

Returns a list of club members. Get this by accessing Club.members or Club.get_members()

members = club.members
print(members[0].name, members[0].role) # prints best player's name and role (sorted by trophies)

Attributes:

Name	Type
`tag`	str
`name`	str
`name_color`	str
`role`	str
`trophies`	int

Ranking¶

Returns a list of top players, clubs, or brawlers. To access this, do ranking[index]

Player/Brawler attributes:

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

Club attributes:

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

Brawler¶

Returns a brawler object with the following attributes. You can retrieve a profile’s brawler info by getting Profile.brawlers

brawlers = profile.brawlers
top_brawler = brawlers[0] # first index in list = highest trophies
print(top_brawler.name, top_brawler.trophies) # prints best brawler's name and trophies

Attributes:

Name	Type
`id`	int
`name`	str
`power`	int
`rank`	int
`trophies`	int
`highest_trophies`	int
`star_powers`	List[SP]

Star Power¶

Attributes:

Name	Type
`id`	int
`name`	str

Battle Logs¶

Returns a list of objects with this structure:

Attributes:

{
    "battleTime":"20190706T151526.000Z",
    "event":{
        "id":15000126,
        "mode":"duoShowdown",
        "map":"Royal Runway"
    },
    "battle":{
        "mode":"duoShowdown",
        "type":"ranked",
        "rank":1,
        "trophyChange":9,
        "teams":[
            [
                {
                    "tag":"#Y2QPGG",
                    "name":"Lex_YouTube",
                    "brawler":{
                        "id":16000005,
                        "name":"SPIKE",
                        "power":10,
                        "trophies":495
                    }
                },
                {
                    "tag":"#8Q229LJY",
                    "name":"Brandon",
                    "brawler":{
                        "id":16000003,
                        "name":"BROCK",
                        "power":10,
                        "trophies":495
                    }
                },
                    {
                    "tag":"#29RGL0QJ0",
                    "name":"smallwhitepeen1",
                    "brawler":{
                        "id":16000007,
                        "name":"JESSIE",
                        "power":7,
                        "trophies":486
                    }
                }
            ],
            [
                {
                    "tag":"#CYLVL8LY",
                    "name":"TST|ROYER™",
                    "brawler":{
                        "id":16000019,
                        "name":"PENNY",
                        "power":8,
                        "trophies":541
                    }
                },
                {
                    "tag":"#8P2URCR0",
                    "name":"ANOTHER",
                    "brawler":{
                        "id":16000023,
                        "name":"LEON",
                        "power":8,
                        "trophies":559
                    }
                },
                {
                    "tag":"#8LRY92QP",
                    "name":"Marshmello",
                    "brawler":{
                        "id":16000021,
                        "name":"GENE",
                        "power":7,
                        "trophies":448
                    }
                }
            ]
        ]
    }
}

Brawlers¶

Returns list of available brawlers and information about them with this structure:

Attributes:

Brawler

]

Exceptions¶

The possible exceptions thrown by the library.

exception brawlstats.errors.RequestError(code, message)[source]¶: The base class for all errors.

exception brawlstats.errors.Forbidden(code, url, message)[source]¶: Raised if your API Key is invalid.

exception brawlstats.errors.NotFoundError(code, **kwargs)[source]¶: Raised if an invalid player tag or club tag has been passed.

exception brawlstats.errors.RateLimitError(code, url)[source]¶: Raised when the rate limit is reached.

exception brawlstats.errors.UnexpectedError(url, code, text)[source]¶: Raised if an unknown error has occured.

exception brawlstats.errors.ServerError(code, url)[source]¶: Raised if the API is down.

Setting Up Logging¶

brawlstats logs errors and debug information via the logging python module. It is strongly recommended that the logging module is configured, as no errors or warnings will be output if it is not set up. Configuration of the logging module can be as simple as

import logging

logging.basicConfig(level=logging.DEBUG)

Placed at the start of the application. This will output the logs from brawlstats as well as other libraries that uses the logging module directly to the console.

The optional level argument specifies what level of events to log out and can any of CRITICAL, ERROR, WARNING, INFO, and DEBUG and if not specified defaults to WARNING.

More advanced setups are possible with the logging module. For example, to write the logs to a file called brawlstars.log instead of outputting them to to the console, the following snippet can be used:

import brawlstats
import logging

logger = logging.getLogger('brawlstats')
logger.setLevel(logging.DEBUG)
handler = logging.FileHandler(filename='brawlstars.log', encoding='utf-8', mode='w')
handler.setFormatter(logging.Formatter('%(asctime)s:%(levelname)s:%(name)s: %(message)s'))
logger.addHandler(handler)

This is recommended, especially at verbose levels such as INFO, and DEBUG as there are a lot of events logged and it would clog the stdout of your program.

Currently, the following things are logged:

DEBUG: API Requests

For more information, check the documentation and tutorial of the logging module.

Welcome to Brawl Stats’ documentation!¶

Features¶

Installation¶

API Reference¶

Data Models¶

Attributes of Data Models¶

Player¶

Club¶

Members¶

Ranking¶

Brawler¶

Star Power¶

Battle Logs¶

Brawlers¶

Exceptions¶

Setting Up Logging¶

Indices¶

BrawlStats

Navigation

Related Topics