clashroyale.py

Installation

Python 3.8 or higher is required.

To install the stable version, do the following:

# Unix / macOS
python3 -m pip install "clashroyale.py"

# Windows
py -m pip install "clashroyale.py"

To install the development version, do the following:

$ git clone https://github.com/Ombucha/clashroyale.py

Make sure you have the latest version of Python installed, or if you prefer, a Python version of 3.8 or greater.

If you have any other issues feel free to search for duplicates and then create a new issue on GitHub with as much detail as possible. Include the output in your terminal, your OS details and Python version.

Client

class clashroyale.Client(token: str, *, session: Session | None = None)

A class that represents a client.

Parameters:

  • token (str) – The Clash Royale API token.

  • session (Optional[requests.Session]) – The session to use.

get_all_global_tournaments() → TournamentList

Gets a list of all global tournaments.

get_all_leaderboards() → List[ClashRoyaleObject]

Gets a list of all available leaderboards.

get_all_locations(*, limit: int | None = None, after: str | None = None, before: str | None = None) → List[ClashRoyaleObject]

Gets a list of all locations.

Parameters:

  • limit (Optional[int]) – The maximum number of items to be returned.

  • after (Optional[str]) – The marker to return items after.

  • before (Optional[str]) – The marker to return items before.

Note

If both before and after are provided, a ValueError is raised.

get_all_season_months() → List[int]

Gets a list of all available season months.

get_cards(*, limit: int | None = None, after: str | None = None, before: str | None = None) → List[ClashRoyaleObject]

Gets a list of cards.

Parameters:

  • limit (Optional[int]) – The maximum number of items to be returned.

  • after (Optional[str]) – The marker to return items after.

  • before (Optional[str]) – The marker to return items before.

Note

If both before and after are provided, a ValueError is raised.

get_challenges() → ChallengeList

Gets a list of current and upcoming challenges.

get_clan(tag: str) → ClashRoyaleObject

Gets information about a single clan.

Parameters:

tag (str) – The tag of the clan.

get_clan_members(tag: str, *, limit: int | None = None, after: str | None = None, before: str | None = None) → ClanMemberList

Gets the members of a clan.

Parameters:

  • tag (str) – The tag of the clan.

  • limit (Optional[int]) – The maximum number of items to be returned.

  • after (Optional[str]) – The marker to return items after.

  • before (Optional[str]) – The marker to return items before.

Note

If both before and after are provided, a ValueError is raised.

get_clan_rankings(location_id: str, *, before: str | None = None, after: str | None = None, limit: int | None = None) → List[ClashRoyaleObject]

Gets global clan rankings or those for a specific location.

Parameters:

  • location_id (str) – The location identifier, or ‘global’ for global rankings.

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_clan_war_rankings(location_id: str, *, before: str | None = None, after: str | None = None, limit: int | None = None) → List[ClashRoyaleObject]

Gets global clan war rankings or those for a specific location.

Parameters:

  • location_id (str) – The location identifier, or ‘global’ for global rankings.

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_current_river_race(tag: str) → ClashRoyaleObject

Gets the current river race for a clan. :param tag: The tag of the clan.

get_leaderboard(leaderboard_id: int, *, before: str | None = None, after: str | None = None, limit: int | None = None) → List[ClashRoyaleObject]

Gets the leaderboard for a specific leaderboard ID.

Parameters:

  • leaderboard_id (int) – The ID of the leaderboard.

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_location(location_id: str) → ClashRoyaleObject

Gets information about a specific location.

Parameters:

location_id (str) – The identifier of the location.

get_path_of_legends_rankings(*, season_id: str, location_id: str, before: str | None = None, after: str | None = None, limit: int | None = None) → List[ClashRoyaleObject]

Gets global Path of Legends rankings.

Parameters:

  • season_id (str) – The identifier of the season.

  • location_id (str) – The location identifier, or ‘global’ for global rankings.

Note

Exactly one of location_id or season_id must be provided.

Parameters:

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_player(tag: str) → ClashRoyaleObject

Gets information about a single player.

Parameters:

tag (str) – The tag of the player.

get_player_battlelog(tag: str) → BattleLog

Gets the recent battles of a player.

Parameters:

tag (str) – The tag of the player.

get_player_rankings(location_id: int, *, before: str | None = None, after: str | None = None, limit: int | None = None) → List[ClashRoyaleObject]

Gets global player rankings or those for a specific location.

Parameters:

  • location_id (int) – The location identifier, or ‘global’ for global rankings.

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_river_race_log(tag: str, *, before: str | None = None, after: str | None = None, limit: int | None = None) → ClanLog

Gets the clan’s river race log.

Parameters:

  • tag (str) – The tag of the clan.

  • limit (Optional[int]) – The maximum number of items to be returned.

  • after (Optional[str]) – The marker to return items after.

  • before (Optional[str]) – The marker to return items before.

Note

If both before and after are provided, a ValueError is raised.

get_season(season_id: str) → ClashRoyaleObject

Gets information about a specific season.

Parameters:

season_id (str) – The identifier of the season.

get_season_rankings(month: str, *, before: str | None = None, after: str | None = None, limit: int | None = None) → List[ClashRoyaleObject]

Gets the rankings for a specific season.

Parameters:

month (str) – The month of the season.

Note

The month is in the format ‘YYYY-MM’, e.g., ‘2018-05’.

Parameters:

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_tournament(tag: str) → ClashRoyaleObject

Gets information about a single tournament.

Parameters:

tag (str) – The tag of the tournament.

get_tournament_rankings(tag: str, *, before: str | None = None, after: str | None = None, limit: int | None = None) → List[ClashRoyaleObject]

Gets the rankings for a specific tournament.

Parameters:

  • tag (str) – The tag of the tournament.

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_upcoming_chests(tag: str) → List[ClashRoyaleObject]

Gets the upcoming chests for a player.

Parameters:

tag (str) – The tag of the player.

get_war_log(tag: str, *, limit: int | None = None, after: str | None = None, before: str | None = None) → ClanLog

Gets the clan’s war log.

Parameters:

  • tag (str) – The tag of the clan.

  • limit (Optional[int]) – The maximum number of items to be returned.

  • after (Optional[str]) – The marker to return items after.

  • before (Optional[str]) – The marker to return items before.

Note

If both before and after are provided, a ValueError is raised.

on_battlelog_update(tag: str, repeat_duration: float | None = 60)

Event that is called when a player’s battlelog is updated.

Parameters:

  • tag (str) – The tag of the player.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_challenges_update(repeat_duration: float | None = 60)

Event that is called when the challenges are updated.

Parameters:

repeat_duration (Optional[float]) – The time to sleep for between every check.

on_clan_rankings_update(location_id: str, repeat_duration: float | None = 60)

Event that is called when the clan rankings for a specific location are updated.

Parameters:

  • location_id (str) – The ID of the location.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_clan_war_rankings_update(location_id: str, repeat_duration: float | None = 60)

Event that is called when the clan war rankings for a specific location are updated.

Parameters:

  • location_id (str) – The ID of the location.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_member_join(tag: str, *, repeat_duration: float | None = 60)

Event that is called when a member joins a clan.

Parameters:

  • tag (str) – The tag of the clan.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_member_leave(tag: str, repeat_duration: float | None = 60)

Event that is called when a member leaves a club.

Parameters:

  • tag (str) – The tag of the club.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_path_of_legends_rankings_update(repeat_duration: float | None = 60, *, season_id: str | None = None, location_id: str | None = None)

Event that is called when the Path of Legends rankings are updated.

Parameters:

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

  • season_id (Optional[str]) – The ID of the season.

  • location_id (Optional[str]) – The ID of the location.

Note

Exactly one of season_id or location_id must be provided.

on_player_rankings_update(location_id: int, repeat_duration: float | None = 60)

Event that is called when the player rankings for a specific location are updated.

Parameters:

  • location_id (int) – The ID of the location.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_river_race_log_update(tag: str, repeat_duration: float | None = 60)

Event that is called when a clan’s river race log is updated.

Parameters:

  • tag (str) – The tag of the clan.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_season_rankings_update(month: str, repeat_duration: float | None = 60)

Event that is called when the season rankings are updated.

Parameters:

month (str) – The month of the season.

Note

The month is in the format ‘YYYY-MM’, e.g., ‘2018-05’.

Parameters:

repeat_duration (Optional[float]) – The time to sleep for between every check.

on_tournament_rankings_update(tag: str, repeat_duration: float | None = 60)

Event that is called when the tournament rankings are updated.

Parameters:

  • tag (str) – The tag of the tournament.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_war_log_update(tag: str, repeat_duration: float | None = 60)

Event that is called when a clan’s war log is updated.

Parameters:

  • tag (str) – The tag of the clan.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

search_clans(*, name: str | None = None, location_id: str | None = None, min_members: int | None = None, max_members: int | None = None, min_score: int | None = None, max_score: int | None = None, limit: int | None = None, after: str | None = None, before: str | None = None) → ClanList

Searches for clans based on various criteria.

Parameters:

  • name (Optional[str]) – The name of the clan.

  • location_id (Optional[str]) – The ID of the location.

  • min_members (Optional[int]) – The minimum number of members in the clan.

  • max_members (Optional[int]) – The maximum number of members in the clan.

  • min_score (Optional[int]) – The minimum score of the clan.

  • max_score (Optional[int]) – The maximum score of the clan.

  • limit (Optional[int]) – The maximum number of items to be returned.

  • after (Optional[str]) – The marker to return items after.

  • before (Optional[str]) – The marker to return items before.

Note

If both before and after are provided, a ValueError is raised.

Note

At least one filtering parameter must be provided.

search_tournaments(*, name: str | None = None, limit: int | None = None, after: str | None = None, before: str | None = None) → TournamentList

Searches for tournaments based on various criteria.

Parameters:

  • name (Optional[str]) – The name of the tournament.

  • limit (Optional[int]) – The maximum number of items to be returned.

  • after (Optional[str]) – The marker to return items after.

  • before (Optional[str]) – The marker to return items before.

Note

If both before and after are provided, a ValueError is raised.

Note

At least one filtering parameter must be provided.

Models

class clashroyale.ClashRoyaleObject(_data: dict | list | tuple)

A class that represents a custom object for the library.

class clashroyale.ClanLog(_data: dict)

A class that represents a clan’s log.

class clashroyale.ClanMemberList(_data: dict)

A class that represents a list of clan members.

class clashroyale.ClanList(_data: dict)

A class that represents a list of clans.

class clashroyale.BattleLog(_data: dict)

A class that represents a battle log.

class clashroyale.TournamentList(_data: dict)

A class that represents a list of tournaments.

class clashroyale.ChallengeList(_data: dict)

A class that represents a list of challenges.

Exceptions

class clashroyale.ClashRoyaleException

Base exception class for this library.

class clashroyale.ForbiddenError

An exception that is raised when access is denied, either because of missing/incorrect credentials or used API token does not grant access to the requested resource.

class clashroyale.MaintenanceError

An exception that is raised when the service is temporarily unavailable because of maintenance.

class clashroyale.RateLimitError

An exception that is raised when the amount of requests was above the threshold defined for the used API token.

class clashroyale.UncallableError

An exception that is raised when a function is not callable.

class clashroyale.UnknownError

An exception that is raised when an unknown error occurs while handling the request.