An asynchronous Python API wrapper for the Brawl Stars API that provides easy access to player statistics, club information, battle logs, and more.
- Fully Asynchronous: Built with
httpxfor high-performance async operations - Type Hints: Complete type annotations for better IDE support and code reliability
- Comprehensive Models: Rich data models for all Brawl Stars entities
- Error Handling: Proper exception handling with custom error types
- Auto Tag Parsing: Automatic handling of Brawl Stars player/club tags
- Session Management: Efficient HTTP session management with connection pooling
- Rate Limiting Ready: Built to handle API rate limits gracefully
- Easy Installation: Available on PyPI for simple pip installation
Install the package from PyPI:
pip install pybrawlstarsFirst, obtain your API key from the Brawl Stars Developer Portal.
importasynciofrompybrawlstarsimportBSClientasyncdefmain():
# Initialize the client with your API keyclient=BSClient("YOUR_API_KEY")
try:
# Get player informationplayer=awaitclient.get_player("2PPQVUQ8J")
print(f"Player: {player.name}")
print(f"Trophies: {player.trophies}")
# Get club informationclub=awaitclient.get_club("2L90CG289")
print(f"Club: {club.name}")
print(f"Members: {len(club.members)}")
finally:
# Always close the client when doneawaitclient.close()
# Run the async functionasyncio.run(main())importasynciofrompybrawlstarsimportBSClientasyncdefmain():
asyncwithBSClient("YOUR_API_KEY") asclient:
player=awaitclient.get_player("2PPQVUQ8J")
print(f"Player: {player.name}")
# Client automatically closes when exiting the contextasyncio.run(main())The main client class for interacting with the Brawl Stars API.
Note: Due to Brawl Stars API limitations, only the following 7 routes are supported:
get_player- Get player profileget_battlelog- Get player battle logget_club- Get club informationget_club_members- Get club membersget_brawlers- Get all brawlersget_brawler- Get specific brawler by IDget_event_rotation- Get current event rotation
BSClient(
api_key: str,
base_url: str="https://api.brawlstars.com",
version: int=1,
timeout: int=10
)# Get player profileawaitclient.get_player(tag: str)
# Get player battle logawaitclient.get_battlelog(tag: str)# Get club informationawaitclient.get_club(tag: str)
# Get club membersawaitclient.get_club_members(tag: str)# Get all brawlersawaitclient.get_brawlers()
# Get specific brawler by IDawaitclient.get_brawler(id: int)# Get current event rotationawaitclient.get_event_rotation()importasynciofrompybrawlstarsimportBSClientasyncdefget_player_stats():
asyncwithBSClient("YOUR_API_KEY") asclient:
player=awaitclient.get_player("PLAYER_TAG")
print(f"🏆 {player.name}")
print(f"Trophies: {player.trophies}")
print(f"Experience Level: {player.exp_level}")
print(f"3v3 Victories: {player.victories_3vs3}")
print(f"Solo Victories: {player.solo_victories}")
print(f"Duo Victories: {player.duo_victories}")
ifplayer.club:
print(f"Club: {player.club.name}")
asyncio.run(get_player_stats())importasynciofrompybrawlstarsimportBSClientasyncdefanalyze_club():
asyncwithBSClient("YOUR_API_KEY") asclient:
club=awaitclient.get_club("CLUB_TAG")
print(f"📊 Club Analysis: {club.name}")
print(f"Description: {club.description}")
print(f"Total Members: {len(club.members)}")
print(f"Required Trophies: {club.required_trophies}")
# Group members by roleroles= {}
formemberinclub.members:
role=member.role.nameroles[role] =roles.get(role, 0) +1print("\n👥 Member Roles:")
forrole, countinroles.items():
print(f" {role}: {count}")
asyncio.run(analyze_club())importasynciofrompybrawlstarsimportBSClientasyncdefanalyze_battles():
asyncwithBSClient("YOUR_API_KEY") asclient:
battles=awaitclient.get_battlelog("PLAYER_TAG")
wins=sum(1forbattleinbattlesifbattle.battle.result=="victory")
total=len(battles)
win_rate= (wins/total) *100iftotal>0else0print(f"⚔️ Recent Battle Performance")
print(f"Total Battles: {total}")
print(f"Victories: {wins}")
print(f"Win Rate: {win_rate:.1f}%")
# Analyze game modesmodes= {}
forbattleinbattles:
mode=battle.event.modemodes[mode] =modes.get(mode, 0) +1print("\n🎮 Game Modes Played:")
formode, countinsorted(modes.items(), key=lambdax: x[1], reverse=True):
print(f" {mode}: {count} battles")
asyncio.run(analyze_battles())importasynciofrompybrawlstarsimportBSClientasyncdeflist_brawlers():
asyncwithBSClient("YOUR_API_KEY") asclient:
brawlers=awaitclient.get_brawlers()
print(f"🤖 Available Brawlers ({len(brawlers)}):")
forbrawlerinsorted(brawlers, key=lambdab: b.name):
print(f"\n{brawler.name} (ID: {brawler.id})")
ifbrawler.star_powers:
print(" Star Powers:")
forspinbrawler.star_powers:
print(f" - {sp.name}")
ifbrawler.gadgets:
print(" Gadgets:")
forgadgetinbrawler.gadgets:
print(f" - {gadget.name}")
asyncio.run(list_brawlers())The library provides rich data models for all API responses:
- Player: Complete player profile with statistics and brawler progression
- Club: Club information including members and settings
- Battle: Individual battle results with participants and outcomes
- Brawler: Brawler information including star powers and gadgets
- Event: Current and upcoming game events
- And many more! Explore all available models in the library
The library provides specific exception types for different error scenarios:
importasynciofrompybrawlstarsimportBSClientfrompybrawlstars.models.errorsimportAPIError, NetworkError, ClientErrorasyncdefsafe_api_call():
asyncwithBSClient("YOUR_API_KEY") asclient:
try:
player=awaitclient.get_player("INVALID_TAG")
exceptAPIErrorase:
print(f"API Error {e.status_code}: {e.message}")
exceptNetworkErrorase:
print(f"Network Error: {e}")
exceptValueErrorase:
print(f"Invalid input: {e}")
exceptTimeoutErrorase:
print(f"Request timed out: {e}")
asyncio.run(safe_api_call())Player and club tags can be provided in multiple formats:
- With hashtag:
#2PPQVUQ8J - Without hashtag:
2PPQVUQ8J
The library automatically handles tag parsing and URL encoding.
- Python 3.8+
- httpx: For async HTTP requests
- typing-extensions: For enhanced type hints (Python < 3.10)
Check PyPI for the latest version and changelog.
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
# Clone the repository
git clone https://github.com/yourusername/pybrawlstars.git
cd pybrawlstars
# Install in development mode
pip install -e .# Install development dependencies
pip install -r requirements-dev.txtThis project is licensed under the MIT License - see the LICENSE file for details.
- Use Context Managers: Always use
async with BSClient()for automatic resource cleanup - Batch Requests: Group related API calls together when possible
- Cache Results: Consider caching frequently accessed data like brawler lists
- Handle Rate Limits: The API has rate limits; implement appropriate delays if needed
- Reuse Client: Create one client instance and reuse it for multiple requests
- 📖 Check the documentation for detailed guides
- 🐛 Report bugs on GitHub Issues
- 💬 Join discussions on GitHub Discussions
Note: This is an unofficial API wrapper. Brawl Stars is a trademark of Supercell Oy.