Skip to content

cocapi

CI Status Pypi version PyPI Downloads Python version License

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

Features

  • Sync & Async — Same API, both modes. Use await in async, plain calls in sync.
  • Automatic Key Management — Log in with developer portal credentials; keys are created, rotated, and persisted automatically.
  • Caching — Built-in TTL-based response cache to reduce API calls.
  • Retries — Exponential backoff on transient failures.
  • Rate Limiting — Async token-bucket rate limiter with burst support.
  • Pagination & Batch — paginate() iterates all pages; batch() fetches many resources at once.
  • Event Polling — Monitor clans, wars, and players in real time with EventStream.
  • Pydantic Models — Optional typed response models with IDE autocompletion.
  • Middleware — Plug in custom request/response processing.
  • Metrics — Track request counts, latencies, and error rates.
  • CLI — Command-line interface for quick lookups.

Quick Example

from cocapi import CocApi

api = CocApi("your_api_token")

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

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

Or with async:

import asyncio
from cocapi import CocApi

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

asyncio.run(main())

Next Steps