Basic Client Interface

The following details all operations on the basic client instance.

class coc.Client(*, key_count: int = 1, key_names: str = 'Created with clashy.py Client', throttle_limit: int = 30, loop: ~asyncio.events.AbstractEventLoop | None = None, correct_tags: bool = True, throttler: ~typing.Type[~coc.http.BasicThrottler | ~coc.http.BatchThrottler] = <class 'coc.http.BasicThrottler'>, connector=None, timeout: float = 30.0, cache_max_size: int = 10000, stats_max_size: int = 1000, load_game_data: ~coc.miscmodels.LoadGameData = <coc.miscmodels.LoadGameData object>, realtime=False, raw_attribute=False, base_url: str = 'https://api.clashofclans.com/v1', ip: str | None = None, lookup_cache: bool | None = True, update_cache: bool | None = True, ignore_cached_errors: ~typing.List[int] | None = None, **kwargs)

This is the client connection used to interact with the Clash of Clans API.

Parameters:

key_count (int) – The amount of keys to use for this client. Maximum of 10. Defaults to 1.
key_names (str) – Default name for keys created to use for this client. All keys created or to be used with this client must have this name. Defaults to “Created with clashy.py Client”.
throttle_limit (int) –
The number of requests per token per second to send to the API. Once hitting this limit, the library will automatically throttle your requests.

Note

Setting this value too high may result in the API rate-limiting your requests. This means you cannot request for ~30-60 seconds.

Warning

Setting this value too high may result in your requests being deemed “API Abuse”, potentially resulting in an IP ban.

Defaults to 10 requests per token, per second.
loop (asyncio.AbstractEventLoop, optional) – The asyncio.AbstractEventLoop to use for HTTP requests. An asyncio.get_event_loop() will be used if None is passed
correct_tags (bool) – Whether the client should correct tags before requesting them from the API. This process involves stripping tags of whitespace and adding a # prefix if not present. Defaults to True.
connector (aiohttp.BaseConnector) – The aiohttp connector to use. By default, this is None.
timeout (float) – The number of seconds before timing out with an API query. Defaults to 30.
cache_max_size (int) – The max size of the internal cache layer. Defaults to 10 000. Set this to None to remove any cache layer.
load_game_data (LoadGameData) – The option for how clashy.py will load game data. See Initialising the Client for more info.
realtime (bool) – Some developers are given special access to an uncached API access by Super Cell. If you are one of those developers, your account will have special flags that will only be interpreted by clashy.py if you set this bool to True.
raw_attribute (bool) – The option to enable the _raw_data attribute for most objects in the library. This attribute will contain the original json data as returned by the API. This can be useful if you want to store a response in a database for later use or are interested in new things that clashy.py does not support otherwise yet. But because this increases the memory footprint and is not needed for most use cases, this defaults to False.
base_url (str) – The base URL to use for API requests. Defaults to “https://api.clashofclans.com/v1”
ip (str) – The IP address to use for API requests. Defaults to None, which means the IP address will be automatically detected.
lookup_cache (bool) – Flag for controlling the cache usage before an actual API request is made. Defaults to True, which means the cache lookup is done
update_cache (bool) – Flag for controlling if the cache is updated after an API request was made. Defaults to True, which means the cache is updated after an API request.
ignore_cached_errors (list[int]) – In case of a cache lookup and a cached entry exists, ignore the cached data if the status code of the response is in the list.
player_cls (Type[Player]) – Class to be used for player objects. Defaults to Player.
member_cls (Type[ClanMember]) – Class to be used for clan member objects. Defaults to ClanMember.
ranke
clan_cls (Type[Clan]) – Class to be used for clan objects. Defaults to Clan.

loop

The loop that is used for HTTP requests

Type:: asyncio.AbstractEventLoop

static_data

The full static game data loaded from game files

Type:: StaticData

async close() → None: Closes the HTTP connection from within a loop function such as async def main()

dispatch(event_name: str, *args, **kwargs) → None: Dispatches an event listener matching the event_name parameter.

async get_builder_base_league(league_id: int, cls: Type[BaseLeague] | None = None, **kwargs) → BaseLeague

Get builder base league information

Parameters:

league_id (str) – The League ID to search for.
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.
NotFound – No league was found with the supplied league ID.

Returns:

The league with the requested ID

Return type:

BaseLeague

async get_builder_base_league_named(league_name: str, cls: Type[BaseLeague] | None = None, **kwargs) → BaseLeague | None

Get a builder base league by name.

This is somewhat equivalent to

leagues = await client.search_builder_base_leagues(limit=None)
return utils.get(leagues, name=league_name)

Parameters:

league_name (str) – The builder base league name to search for
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The first league matching the league name. Could be None if not found.

Return type:

BaseLeague

async get_capital_league(league_id: int, cls: Type[BaseLeague] | None = None, **kwargs) → BaseLeague

Get capital league information

Parameters:

league_id (str) – The League ID to search for.
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.
NotFound – No league was found with the supplied league ID.

Returns:

The league with the requested ID

Return type:

BaseLeague

async get_capital_league_named(league_name: str, cls: Type[BaseLeague] | None = None, **kwargs) → BaseLeague | None

Get a capital league by name.

This is somewhat equivalent to

leagues = await client.search_capital_leagues(limit=None)
return utils.get(leagues, name=league_name)

Parameters:

league_name (str) – The capital league name to search for
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The first league matching the league name. Could be None if not found.

Return type:

BaseLeague

async get_clan(tag: str, cls: Type[Clan] | None = None, **kwargs) → Clan

Get information about a single clan by clan tag.

Clan tags can be found using clan search operation.

Parameters:

tag (str) – The clan tag to search for.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of Clan.
NotFound – No clan was found with the supplied tag.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The clan with provided tag.

Return type:

Clan

async get_clan_labels(*, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[Label] | None = None, **kwargs) → List[Label]

Fetch all possible clan labels.

Parameters:

limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned.#

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

A list of all possible clan labels.

Return type:

List[Label]

async get_clan_war(clan_tag: str, cls: Type[ClanWar] | None = None, **kwargs) → ClanWar

Retrieve information about clan’s current clan war

Parameters:

clan_tag (str) – The clan tag to search for.

Raises:

TypeError – The cls parameter must be a subclass of ClanWar.
NotFound – No clan was found with the supplied tag.
PrivateWarLog – The clan’s war log is private.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The clan’s current war.

Return type:

ClanWar

get_clan_wars(clan_tags: Iterable[str], cls: Type[ClanWar] | None = None, **kwargs) → AsyncIterator[ClanWar]

Retrieve information multiple clan’s current clan wars

This returns a coc.WarIterator which fetches the requested wars in parallel.

Note

This will skip any clans who have a private war-log.

Note

This will not fetch any CWL wars. Use Client.get_current_wars() for that.

Example

tags = [...]
async for clan_war in Client.get_clan_wars(tags):
    print(clan_war.opponent)

Parameters:

clan_tags (Iterable[str]) – An iterable of clan tags to search for.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of ClanWar.
NotFound – No clan was found with the supplied tag.
PrivateWarLog – The clan’s warlog is private.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Yields:

ClanWar – A war matching one of the tags requested.

get_clans(tags: Iterable[str], cls: Type[Clan] | None = None, **kwargs) → AsyncIterator[Clan]

Get information about multiple clans by clan tag. Refer to Client.get_clan for more information.

This returns a ClanIterator which fetches the requested clan tags in parallel.

Example

tags = [...]
async for clan in client.get_clans(tags):
    print(clan.name)

Parameters:

tags (Iterable[str]) – An iterable of clan tags to search for.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of Clan.

Yields:

Clan – A clan matching one of the tags requested.

async get_current_goldpass_season(cls: Type[GoldPassSeason] | None = None, **kwargs) → GoldPassSeason

Get the current gold pass season

Parameters:

cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The gold pass season object of the current season

Return type:

GoldPassSeason

async get_current_war(clan_tag: str, cwl_round: WarRound = WarRound.current_war, cls: Type[ClanWar] | None = None, **kwargs) → ClanWar | None

Retrieve a clan’s current war.

Unlike Client.get_clan_war or Client.get_league_war, this method will search for a regular war, and if the clan is in notInWar state, search for a current league war.

This simplifies what would otherwise be 2-3 function calls to find a war.

If you don’t wish to search for CWL wars, use Client.get_clan_war().

This method will consume the PrivateWarLog error, instead returning None.

Note

You can differentiate between a regular clan war and a clan war league (CWL) war by using the helper property, ClanWar.is_cwl.

Parameters:

clan_tag (str) – An iterable of clan tag to search for.
cwl_round (WarRound) – An enum detailing the type of round to get. Could be coc.WarRound.previous_war, coc.WarRound.current_war or coc.WarRound.preparation. This defaults to coc.WarRound.current_war.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of ClanWar.
NotFound – No clan was found with the supplied tag.
PrivateWarLog – The clan’s warlog is private.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The clan’s current war. Could be None.

If the clan is in CWL, the league group can be accessed via ClanWar.league_group.

If you pass in a WarRound and that round doesn’t exist (yet), this will return None.

Return type:

ClanWar

get_current_wars(clan_tags: Iterable[str], cls: Type[ClanWar] | None = None, **kwargs) → AsyncIterator[ClanWar]

Retrieve information multiple clan’s current wars.

See Client.get_current_war() for more information.

This returns a CurrentWarIterator which fetches the requested clan tags in parallel.

Note

This will skip any clans who have a private war-log.

Note

This will fetch CWL wars, which may result in a slower operation due to multiple API calls. If you only wish to get regular wars, consider Client.get_clan_wars().

Example

tags = [...]
async for war in Client.get_current_wars(tags):
    print(war.type)

Parameters:

clan_tags (Iterable[str]) – An iterable of clan tags to search for.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of ClanWar.

Yields:

ClanWar – The clan war of a requested tag.

get_equipment(name: str, level: int = 0) → Equipment | None

Get an Equipment object with the given name and level.

Example

gear = client.get_equipment("Dark Orb", level=10)
print(f"{gear.name} has {gear.upgrade_cost} upgrade cost at Lv{gear.level}")

Parameters:

name (str) – The equipment name, which must match in-game exactly, and is case-sensitive.
level (int) – The level of the equipment. Defaults to 1.

Returns:

An Equipment object at the specified level, or None if the equipment is not found.

Return type:

Optional[Equipment]

get_extended_cwl_group_data(name: str) → ExtendedCWLGroup | None

Get extended CWL group data by league name.

Example

cwl_group = client.get_extended_cwl_group_data("Champion League I")
print(f"{cwl_group.name}: {cwl_group.first_place_medals} medals for 1st place")

Parameters:: name (str) – The CWL league name, which must match in-game exactly, and is case-sensitive.
Returns:: An ExtendedCWLGroup object containing CWL league information, or None if not found.
Return type:: Optional[ExtendedCWLGroup]

get_hero(name: str, level: int = 0) → Hero | None

Get a Hero object with the given name and level.

Example

hero = client.get_hero("Archer Queen", level=50)
print(f"{hero.name} has {hero.upgrade_cost} upgrade cost at Lv{hero.level}")

Parameters:

name (str) – The hero name, which must match in-game exactly, and is case-sensitive.
level (int) – The level of the hero. Defaults to 1.

Returns:

A Hero object at the specified level, or None if the hero is not found.

Return type:

Optional[Hero]

async get_league(league_id: int, cls: Type[League] | None = None, **kwargs) → League

Get league information

Parameters:

league_id (str) – The League ID to search for.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.
NotFound – No league was found with the supplied league ID.

Returns:

The league with the requested ID

Return type:

League

async get_league_group(clan_tag: str, cls: Type[ClanWarLeagueGroup] | None = None, **kwargs) → ClanWarLeagueGroup

Retrieve information about clan’s current clan war league group.

Parameters:

clan_tag (str) – The clan tag to search for.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of ClanWarLeagueGroup.
NotFound – No clan was found with the supplied tag.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception. This may be due to an API bug whereby requesting the league group of a clan searching for a CWL match will time out.

Returns:

The clan’s war league group.

Return type:

ClanWarLeagueGroup

async get_league_named(league_name: str, cls: Type[League] | None = None, **kwargs) → League | None

Get a league by name.

This is somewhat equivalent to

leagues = await client.search_leagues(limit=None)
return utils.get(leagues, name=league_name)

Parameters:

league_name (str) – The league name to search for
cls – Target class to use to model that data returned

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The first league matching the league name. Could be None if not found.

Return type:

League

async get_league_war(war_tag: str, cls: Type[ClanWar] | None = None, **kwargs) → ClanWar

Retrieve information about a clan war league war.

Parameters:

war_tag (str) – The league war tag to search for.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of ClanWar.
NotFound – No clan was found with the supplied tag.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The league war associated with the war tag

Return type:

ClanWar

get_league_wars(war_tags: Iterable[str], clan_tag: str | None = None, cls: Type[ClanWar] | None = None, **kwargs) → AsyncIterator[ClanWar]

Retrieve information about multiple league wars

This returns a LeagueWarIterator which fetches the requested clan tags in parallel.

Example

tags = [...]
async for league_war in Client.get_league_wars(tags):
    print(league_war.opponent)

Parameters:

war_tags (Iterable[str]) – An iterable of war tags to search for.
clan_tag (str) – An optional clan tag. If present, this will only return wars which belong to this clan.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of ClanWar.

Yields:

ClanWar – A war matching one of the tags requested.

async get_location(location_id: int, cls: Type[Location] | None = None, **kwargs) → Location

Get information about specific location

Parameters:

location_id (int) – The Location ID to search for.
cls – Target class to use to model that data returned

Raises:

NotFound – No location was found with the supplied ID.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The requested location.

Return type:

Location

async get_location_clans(location_id: int = 'global', *, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[RankedClan] | None = None, **kwargs) → List[RankedClan]

Get clan rankings for a specific location

Parameters:

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of RankedClan.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The top clans for the requested location.

Return type:

List[RankedClan]

async get_location_clans_builder_base(location_id: int = 'global', *, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[RankedClan] | None = None, **kwargs) → List[RankedClan]

Get clan builder base rankings for a specific location

Parameters:

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of RankedClan.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The top builder base-clans for the requested location.

Return type:

List[RankedClan]

async get_location_clans_capital(location_id: int = 'global', *, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[RankedClan] | None = None, **kwargs) → List[RankedClan]

Get clan capital rankings for a specific location

Parameters:

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of RankedClan.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The top clans for the requested location.

Return type:

List[RankedClan]

async get_location_named(location_name: str, cls: Type[Location] | None = None, **kwargs) → Location | None

Get a location by name.

This is equivalent to:

locations = await client.search_locations(limit=None)
return utils.get(locations, name=location_name)

Parameters:

location_name (str) – The location name to search for
cls – Target class to use to model that data returned

Returns:

The first location matching the location name.

Return type:

Location

async get_location_players(location_id: int = 'global', *, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[RankedPlayer] | None = None, **kwargs) → List[RankedPlayer]

Get player rankings for a specific location

Parameters:

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of RankedPlayer.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The top players for the requested location.

Return type:

List[RankedPlayer]

async get_location_players_builder_base(location_id: int = 'global', *, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[RankedPlayer] | None = None, **kwargs) → List[RankedPlayer]

Get player builder base rankings for a specific location

Parameters:

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of RankedPlayer.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The top builder base players for the requested location.

Return type:

List[RankedPlayer]

async get_members(clan_tag: str, *, limit: int = 0, after: str = '', before: str = '', cls: Type[ClanMember] | None = None, **kwargs) → List[ClanMember]

List clan members.

This is equivilant to (await Client.get_clan('tag')).members.

Parameters:

clan_tag (str) – The clan tag to search for.
cls – Target class to use to model that data returned
limit – class:int: Number of members to retrieve
after – class:str: Pagination string to get page after
before – class:str: Pagination string to get page before

Raises:

TypeError – The cls parameter must be a subclass of ClanMember.
NotFound – No clan was found with the supplied tag.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

A list of members in the clan.

Return type:

List[ClanMember]

get_pet(name: str, level: int = 0) → Pet | None

Get a Pet object with the given name and level.

Example

pet = client.get_pet("Electro Owl", level=5)
print(f"{pet.name} has {pet.upgrade_cost} upgrade cost at Lv{pet.level}")

Parameters:

name (str) – The pet name, which must match in-game exactly, ahd is case-sensitive.
level (int) – The level of the pet. Defaults to 1.

Returns:

A Pet object at the specified level, or None if the pet is not found.

Return type:

Optional[Pet]

async get_player(player_tag: str, cls: ~typing.Type[~coc.players.Player] = <class 'coc.players.Player'>, load_game_data: bool | None = None, **kwargs) → Player

Get information about a single player by player tag. Player tags can be found either in game or by from clan member lists.

Parameters:

player_tag (str) – The player tag to search for.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of Player.
NotFound – No player was found with the supplied tag.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The player with the tag.

Return type:

Player

async get_player_labels(*, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[Label] | None = None, **kwargs) → List[Label]

Fetch all possible player labels.

Parameters:

limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

A list of all possible player labels.

Return type:

List[Label]

get_players(player_tags: Iterable[str], cls: Type[Player] | None = None, load_game_data: bool | None = None, **kwargs) → AsyncIterator[Player]

Get information about a multiple players by player tag. Player tags can be found either in game or by from clan member lists.

This returns a PlayerIterator which fetches the requested player tags in parallel.

Example

tags = [...]
async for player in Client.get_players(tags):
    print(player)

Parameters:

player_tags (Iterable[str]) – An iterable of player tags to search for.
cls – Target class to use to model that data returned

Raises:

TypeError – The cls parameter must be a subclass of Player.

Yields:

Player – A player matching one of the tags requested.

async get_raid_log(clan_tag: str, cls: Type[RaidLogEntry] | None = None, page: bool = False, *, limit: int = 0, after: str = '', before: str = '', **kwargs) → RaidLog

Retrieve a clan’s Capital Raid Log. By default, this will return all the clan’s log available in the API. This will of course consume memory. The option of limiting the amount of log items fetched can be controlled with the limit parameter. Additionally, if paginate is set to True, and an async for loop is performed on this object, then additional log items will be fetched but only consume the same amount of memory space at all time.

Parameters:

clan_tag – class:str: The clan tag to search for.
cls – Target class to use to model that data returned
page – class:bool: Enable fetching logs while only holding the same amount of logs as limit. If paginate is set to True, and limit is set to default of 0, then limit will be set to 10 automatically.
limit – class:int: Number of logs to retrieve
after – class:str: Pagination string to get page after
before – class:str: Pagination string to get page before

Raises:

TypeError – The cls parameter must be a subclass of RaidLogEntry.
NotFound – No clan was found with the supplied tag.
PrivateWarLog – The clan’s warlog is private.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

Entries in the capital raid seasons of the requested clan.

Return type:

RaidLog

async get_season_rankings(league_id: int, season_id: str, cls: Type[RankedPlayer] | None = None, **kwargs) → AsyncIterator[RankedPlayer]

Get league season rankings.

Note

League season information is available only for Legend League, with a league ID 29000022.

Parameters:

league_id (str) – The League ID to search for.
season_id (str) – The Season ID to search for.
cls – Target class to use to model that data returned.

Raises:

InvalidArgument – An invalid league_id or season_id was supplied. Currently, the only league supported is legends.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

Top players for the requested season and league.

Return type:

List[RankedPlayer]

async get_seasons(league_id: int = 29000022, **kwargs) → List[str]

Get league seasons.

Note

League season information is available only for Legend League, with a league ID 29000022.

Parameters:

league_id (str) – The League ID to search for. Defaults to the only league you can get season information for, legends.
cls – Target class to use to model that data returned.

Raises:

InvalidArgument – An invalid league_id was supplied. Currently, the only league supported is legends.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The legend season IDs, in the form YYYY-MM, ie. 2020-04.

Return type:

List[str]

get_spell(name: str, level: int = 0) → Spell | None

Get a Spell object with the given name and level.

Example

spell = client.get_spell("Healing Spell", level=3)
print(f"{spell.name} has {spell.upgrade_cost} upgrade cost at Lv{spell.level}")

Parameters:

name (str) – The spell name, which must match in-game exactly, and is case-sensitive.
level (int) – The level of the spell. Defaults to 1.

Returns:

A Spell object at the specified level, or None if the spell is not found.

Return type:

Optional[Spell]

get_translation(translation_id: str) → Translation | None

Get translation data for a given Translation ID (TID).

Example

translation = client.get_translation("TID_HERO_PALADIN_CHAMPION")
if translation:
    print(f"English: {translation.english}")
    print(f"Russian: {translation.russian}")
    print(f"By code: {translation['RU']}")

Parameters:: TID (str) – The Translation ID string (e.g., “TID_HERO_PALADIN_CHAMPION”).
Returns:: A Translation object with all language translations, or None if the TID is not found.
Return type:: Translation | None

get_troop(name: str, is_home_village: bool = True, level: int = 0) → Troop | None

Get a Troop object with the given name and level.

Example

troop = client.get_troop("Barbarian", level=5)
print(f"{troop.name} has {troop.dps} DPS at Lv{troop.level}")

Parameters:

name (str) – The troop name, which must match in-game exactly, and is case-sensitive.
is_home_village (bool) – Whether the troop belongs to the home village or builder base. Defaults to True (home village).
level (int) – The level of the troop. Defaults to 1.

Returns:

A Troop object at the specified level, or None if the troop is not found.

Return type:

Optional[Troop]

async get_war_league(league_id: int, cls: Type[BaseLeague] | None = None, **kwargs) → BaseLeague

Get war league information

Parameters:

league_id (str) – The League ID to search for.
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.
NotFound – No league was found with the supplied league ID.

Returns:

The league with the requested ID

Return type:

BaseLeague

async get_war_league_named(league_name: str, cls: Type[BaseLeague] | None = None, **kwargs) → BaseLeague | None

Get a war league by name.

This is somewhat equivalent to

leagues = await client.search_war_leagues(limit=None)
return utils.get(leagues, name=league_name)

Parameters:

league_name (str) – The war league name to search for
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The first league matching the league name. Could be None if not found.

Return type:

BaseLeague

async get_war_log(clan_tag: str, cls: Type[ClanWarLogEntry] | None = None, page: bool = False, *, limit: int = 0, after: str = '', before: str = '', **kwargs) → ClanWarLog

Retrieve a clan’s clan war log. By default, this will return all the clan’s log available in the API. This will of course consume memory. The option of limiting the amount of log items fetched can be controlled with the limit parameter. Additionally, if paginate is set to True, and an async for loop is performed on this object, then additional log items will be fetched but only consume the same amount of memory space at all time.

Note

Please see documentation for ClanWarLogEntry for different attributes which are present when the entry is a regular clan war or a league clan war. The difference can be found with ClanWarLogEntry.is_league_entry.

Parameters:

clan_tag – class:str: The clan tag to search for.
cls – Target class to use to model that data returned
page – class:bool: Enable fetching logs while only holding the same amount of logs as limit. If paginate is set to True, and limit is set to default of 0, then limit will be set to 10 automatically.
limit – class:int: Number of logs to retrieve
after – class:str: Pagination string to get page after
before – class:str: Pagination string to get page before

Raises:

TypeError – The cls parameter must be a subclass of ClanWarLogEntry.
NotFound – No clan was found with the supplied tag.
PrivateWarLog – The clan’s warlog is private.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

Entries in the warlog of the requested clan.

Return type:

ClanWarLog

async login(email: str, password: str) → None

Retrieves all keys and creates an HTTP connection ready for use.

Parameters:

email (str) – Your password email from https://developer.clashofclans.com This is used when updating keys automatically if your IP changes
password (str) – Your password login from https://developer.clashofclans.com This is used when updating keys automatically if your IP changes

login_with_keys(*keys: str) → None

Creates an HTTP connection ready for use with the keys you provide.

Deprecated since version v2.3.0: This function has been deemed deprecated to allow asyncio to clean up the async structures. Please use Client.login_with_tokens() instead.

Parameters:: keys (list[str]) – Keys or tokens as found from https://developer.clashofclans.com.

async login_with_tokens(*tokens: str) → None

Creates an HTTP connection ready for use with the tokens you provide.

Parameters:: tokens (list[str]) – Tokens as found from https://developer.clashofclans.com under “My account” -> <your key> -> “token”.

parse_account_data(data: dict) → AccountData

Parse account data JSON from in-game into an AccountData object.

Parameters:: data (dict) – The raw account data.
Returns:: An AccountData object containing parsed account information.
Return type:: AccountData

parse_army_link(link: str) → ArmyRecipe

Transform an army link from in-game into an ArmyRecipe object.

Example

army = client.parse_army_link("https://link.clashofclans.com/en?action=CopyArmy&army=u10x0-2x3s1x9-3x2")

for troop, quantity in army.troops:
    print("The user wants {} {}s. They each have {} DPS.".format(quantity, troop.name, troop.dps))

for spell, quantity in army.spells:
    print("The user wants {} {}s.".format(quantity, spell.name))

for hero_loadout in army.heroes_loadout:
    print("Hero: {}, Pet: {}, Equipment: {}".format(
        hero_loadout.hero.name,
        hero_loadout.pet.name if hero_loadout.pet else None,
        [eq.name for eq in hero_loadout.equipment]
    ))

Parameters:

link (str) – The army share link, as copied from in-game. It should look something like: https://link.clashofclans.com/en?action=CopyArmy&army=u10x0-2x3s1x9-3x2

Raises:

RuntimeError – Troop and Spell game metadata must be loaded to use this feature.

Returns:

An ArmyRecipe object with the following attributes:

heroes_loadout: List[HeroLoadout] - Hero loadouts with pets and equipment
troops: List[Tuple[Troop, int]] - Troops with their quantities
spells: List[Tuple[Spell, int]] - Spells with their quantities
clan_castle_troops: List[Tuple[Troop, int]] - Clan castle troops with quantities
clan_castle_spells: List[Tuple[Spell, int]] - Clan castle spells with quantities

Return type:

ArmyRecipe

async search_builder_base_leagues(*, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[BaseLeague] | None = None, **kwargs) → List[BaseLeague]

Get list of builder base leagues.

Parameters:

limit (int) – Number of items to fetch. Defaults to None (all leagues).
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The requested leagues.

Return type:

List[BaseLeague]

async search_capital_leagues(*, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[BaseLeague] | None = None, **kwargs) → List[BaseLeague]

Get list of capital leagues.

Parameters:

limit (int) – Number of items to fetch. Defaults to None (all leagues).
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The requested leagues.

Return type:

List[BaseLeague]

Search all clans by name and/or filtering the results using various criteria.

At least one filtering criteria must be defined and if name is used as part of search, it is required to be at least three characters long.

Parameters:

name (str, optional) – The clan name.
war_frequency (str, optional) – The war frequency.
location_id (int, optional) – The location id.
min_members (int, optional) – The minimum number of members.
max_members (int, optional) – The maximum number of members.
min_clan_points (int, optional) – The minumum clan points.
min_clan_level (int, optional) – The minimum clan level.
label_ids (List`[Union[:class:`coc.Label, int]]) – List of Labels or Label ids
limit (int) – The number of clans to search for.
cls – Target class to use to model that data returned

Raises:

RuntimeError – At least one filtering parameter must be passed.
TypeError – The cls parameter must be a subclass of Clan.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

A list of all clans found matching criteria provided.

Return type:

List[Clan]

async search_leagues(*, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[League] | None = None, **kwargs) → List[League]

Get list of leagues.

Parameters:

limit (int) – Number of items to fetch. Defaults to None (all leagues).
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The requested leagues.

Return type:

List[League]

async search_locations(*, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[Location] | None = None, **kwargs) → List[Location]

List all available locations

Parameters:

limit (int, optional) – Number of items to fetch. Default is None, which returns all available locations
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The requested locations.

Return type:

List[Location]

async search_war_leagues(*, limit: int | None = None, before: str | None = None, after: str | None = None, cls: Type[BaseLeague] | None = None, **kwargs) → List[BaseLeague]

Get list of war leagues.

Parameters:

limit (int) – Number of items to fetch. Defaults to None (all leagues).
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.
cls – Target class to use to model that data returned.

Raises:

Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

The requested leagues.

Return type:

List[BaseLeague]

set_object_cls(name: str, cls)

Set a custom class type for a given object name. The method ensures that the provided class is a valid subclass of a predefined default class. It updates the internal mapping of object classes to the new custom class.

Note

This affects only the return type of Client methods returning the object. For example changing the ClanMember class to a custom class will affect ‘get_clan_members’, but not the clan members of a clan object obtained by calling get_clan or get_clans methods.

Parameters:

name (str) – The name of the object whose class type is to be set. It must be one of the predefined object types such as “Player”, “Clan”, etc.
cls – The custom class type to be associated with the given object name. The class must be a subclass of the corresponding default class type.

Raises:

ValueError – If the provided object name is not supported.
TypeError – If the provided class is not a subclass of the default class for the given object name.

async verify_player_token(player_tag: str, token: str, **kwargs) → bool

Verify player API token that can be found from the game settings.

This can be used to check that players own the game accounts they claim to own as they need to provide the one-time use API token that exists inside the game.

Parameters:

player_tag (str) – The player tag to verify.
token (str) – The player’s API token to verify.

Raises:

NotFound – No player was found with the supplied tag.
Maintenance – The API is currently in maintenance.
GatewayError – The API hit an unexpected gateway exception.

Returns:

Whether the player tag and API token were a valid match.

Return type:

bool