Skip to main content

A python wrapper for the Clash of Clans API

Project description

Discord Server Invite PyPI version info PyPI supported Python versions Travis CI info

Easy to use asynchronous Clash of Clans API wrapper in Python.

Key Features

  • Asynchronous code
  • Entire coverage of the official Clash of Clans API
  • Email/password login removes the stress of managing tokens
  • Optimised for speed and performance
  • Completely customisable cache

Getting Started


Python 3.5 or higher is required

# Linux/macOS
python3 -m pip install -U

# Windows
py -3 -m pip install -U

# to install the development version:
python3 -m pip install -U git+

Quick Example

This is the basic usage of the library. This example will get a player with a certain tag, and search for 5 clans with a name.

import coc
import asyncio

client = coc.login('email', 'password')
loop = asyncio.get_event_loop()

player = loop.run_until_complete(client.get_player('tag'))

async def get_five_clans(name):
    players = await client.search_clans(name=name, limit=5)
    for n in players:
        print(n, n.tag)

if __name__ == '__main__':

Basic Events Example

This script will run forever, printing to the terminal whenever someone joins the clan.

import coc
import asyncio

client = coc.login('email', 'password', client=coc.EventsClient)

async def on_clan_member_join(player, clan):
    print('{} ({0.tag}) just joined {} ({1.tag})!'.format(player, clan))



For more examples see the examples directory


Contributing is fantastic and much welcomed! If you have an issue, feel free to open an issue and start working on it. A few things to bear in mind:

Installing the dev requirements:

pip install -r dev-requirements.txt

This will install all the dev requirements, such as pylint, sphinx and pre-commit. These are handy!

Setting up a git pre-commit hook

Code quality is important - the repo has automatic linting and CI implemented.

In order to keep the git history clean, a pre-commit hook will automatically lint your code according to the repo’s standard before you push.

You can install this pre-commit hook with:

pre-commit install

In your local terminal. The pre-commit module should have already been installed if you installed the dev-requirements

You can run all linting that will be run in CI with:

python lint
// or
pre-commit run --all-files


  • This content is not affiliated with, endorsed, sponsored, or specifically approved by Supercell and Supercell is not responsible for it. For more information see Supercell’s Fan Content Policy:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for, version 0.3.3
Filename, size File type Python version Upload date Hashes
Filename, size (63.0 kB) File type Wheel Python version py3 Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page