cocapi

A Python wrapper for the official Clash of Clans API with full async support, automatic key management, caching, retries, and optional Pydantic models.

Full Documentation

Features

• Sync & async — same methods, same names, both modes
• Automatic key management — login with email/password, keys are created, reused, and rotated automatically
• Caching — TTL-based response caching with stats
• Retries — exponential backoff for rate limits and server errors
• Pagination & batch — paginate() auto-follows cursors, batch() fetches many resources at once
• Event polling — real-time monitoring of clans, wars, and players with async for or callbacks
• Pydantic models — optional typed response objects with IDE autocompletion
• Middleware — plug in custom request/response processing
• CLI — cocapi clan "#2PP" from the terminal
• Maintenance detection — automatic detection of API maintenance windows

Install

pip install cocapi

# With Pydantic model support
pip install 'cocapi[pydantic]'

# With CLI
pip install 'cocapi[cli]'

Requires Python 3.10+.

Quick Start

With an API Token

Get a token from developer.clashofclans.com:

from cocapi import CocApi

api = CocApi("your_api_token")

clan = api.clan_tag("#2PP")
print(clan["name"])

player = api.players("#900PUCPV")
print(player["trophies"])

With Email/Password (Automatic Key Management)

Skip manual key creation entirely. cocapi logs into the developer portal, detects your IP, and manages keys for you:

from cocapi import CocApi

api = CocApi.from_credentials("you@example.com", "your_password")
clan = api.clan_tag("#2PP")

Keys are created automatically, reused when valid, and rotated when your IP changes. See the Authentication guide for details.

Async

import asyncio
from cocapi import CocApi

async def main():
    async with CocApi("your_token") as api:
        clan = await api.clan_tag("#2PP")
        player = await api.players("#900PUCPV")
        print(clan["name"], player["trophies"])

asyncio.run(main())

See the Async guide for more patterns.

Configuration

All options are set through ApiConfig:

from cocapi import CocApi, ApiConfig

config = ApiConfig(
    timeout=30,
    max_retries=3,
    enable_caching=True,
    cache_ttl=600,
    enable_rate_limiting=True,     # async only
    requests_per_second=10.0,
    enable_metrics=True,
    use_pydantic_models=True,      # requires cocapi[pydantic]
)

api = CocApi("your_token", config=config)

See the Configuration guide for all options.

Pagination & Batch

# Auto-paginate through all clan members
for member in api.paginate(api.clan_members, "#CLAN_TAG"):
    print(member["name"])

# Fetch multiple players at once
results = api.batch(api.players, ["#TAG1", "#TAG2", "#TAG3"])

Both work in sync and async. See the Pagination & Batch guide.

Event Polling

Monitor clans, wars, and players in real time. Async only.

from cocapi.events import EventStream, EventType

async with CocApi("token") as api:
    stream = EventStream(api)
    stream.watch_clans(["#2PP"], interval=60)
    stream.watch_wars(["#2PP"], interval=30)
    stream.watch_players(["#900PUCPV"], interval=120)

    async with stream:
        async for event in stream:
            print(event.event_type, event.tag)
            for change in event.changes:
                print(f"  {change.field}: {change.old_value} -> {change.new_value}")

Supports 20+ event types including member join/leave, war state transitions, troop/hero upgrades, maintenance detection, and more. See the Event Polling guide.

CLI

pip install 'cocapi[cli]'

# Login once (key is persisted)
cocapi login --email you@example.com --password yourpass

# Use without --token
cocapi clan "#2PP"
cocapi player "#900PUCPV"
cocapi war "#2PP"
cocapi search "clash" --limit 5
cocapi goldpass

See the CLI guide for all commands.

Error Handling

All endpoints return a dict (or Pydantic model). Errors never raise exceptions:

result = api.clan_tag("#INVALID")
if result.get("result") == "error":
    print(result["message"])       # Human-readable message
    print(result["error_type"])    # "timeout", "connection", "http", "json", etc.
    print(result.get("status_code"))

See the Error Handling guide.

Examples

Runnable scripts in the examples/ folder:

Script	What it covers
basic_usage.py	Sync: clan info, player info, search, error handling
async_usage.py	Async with context manager, concurrent requests
credential_auth.py	Email/password login, key persistence, auto-refresh
pagination_batch.py	paginate() and batch() in sync and async
event_polling.py	EventStream with async for — real-time monitoring
event_callbacks.py	@stream.on() decorators and stream.run()
configuration.py	ApiConfig, caching, metrics, middleware

API Reference

Full API reference with all endpoints, parameters, and response schemas is available in the documentation.

Key classes:

• CocApi — main entry point (sync/async)
• ApiConfig — configuration options
• EventStream — real-time event polling
• Pydantic Schemas — typed response models
• All Endpoints — every API method

Credits

• All Contributors

cocapi is not affiliated with SuperCell.