| Name | cocapi JSON |
| Version |
3.0.1
JSON |
| download |
| home_page | None |
| Summary | A python wrapper around clash of clans api |
| upload_time | 2025-08-10 08:28:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7.2 |
| license | GPL-3.0 |
| keywords |
api
clans
clash
supercell
wrapper
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p>
<a href="https://github.com/tonybenoy/cocapi/actions">
<img src="https://github.com/tonybenoy/cocapi/workflows/CI/badge.svg" alt="CI Status" height="20">
</a>
<a href="https://pypi.org/project/cocapi/"><img src="https://img.shields.io/pypi/v/cocapi" alt="Pypi version" height="21"></a>
</p>
<p>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.7+-blue.svg" alt="Python version" height="17"></a>
<a href="https://github.com/tonybenoy/cocapi/blob/master/LICENSE"><img src="https://img.shields.io/github/license/tonybenoy/cocapi" alt="License" height="17"></a>
<a href="https://github.com/astral-sh/ruff">
<img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" height="17">
</a>
</p>
# ClashOfClansAPI v3.0.0
A high-performance Python wrapper for SuperCell's Clash of Clans API with enterprise-grade features including async support, response caching, retry logic, middleware system, and comprehensive metrics.
**🎯 Complete API Coverage**: All 22 official endpoints implemented
**⚡ High Performance**: Async support with intelligent caching and rate limiting
**🔄 100% Backward Compatible**: Drop-in replacement for existing code
**🛡️ Production Ready**: Retry logic, middleware pipeline, metrics tracking, and comprehensive error handling
**🚀 Future-Proof**: Custom endpoint support and dynamic Pydantic models
Get Token from [https://developer.clashofclans.com/](https://developer.clashofclans.com/)
## ✨ Key Features
- **🔄 Sync & Async Support**: Same API works for both sync and async
- **🚀 Custom Endpoints**: Future-proof with any new SuperCell endpoints
- **💾 Intelligent Caching**: Response caching with configurable TTL and statistics
- **🔁 Smart Retry Logic**: Exponential backoff with configurable retry policies
- **⚡ Rate Limiting**: Built-in protection against API rate limits (async mode)
- **🛡️ Comprehensive Error Handling**: Detailed error messages and types
- **📊 Metrics & Analytics**: Request performance tracking and insights
- **🔌 Middleware System**: Pluggable request/response processing pipeline
- **🎯 Type Safety**: Complete type hints and optional Pydantic models
- **🌐 Base URL Configuration**: Support for proxies and testing environments
- **🔄 100% Backward Compatible**: Drop-in replacement for existing code
# Install
```bash
# Standard installation (dict responses)
pip install cocapi
# With optional Pydantic models support
pip install 'cocapi[pydantic]'
```
# Usage Examples
## Basic Synchronous Usage (Backward Compatible)
```python
from cocapi import CocApi
token = 'YOUR_API_TOKEN'
timeout = 60 # requests timeout
# Basic initialization (same as before)
api = CocApi(token, timeout)
# With status codes (same as before)
api = CocApi(token, timeout, status_code=True)
```
## Advanced Configuration
```python
from cocapi import CocApi, ApiConfig
# Enterprise-grade configuration
config = ApiConfig(
# Performance settings
timeout=30,
max_retries=5,
retry_delay=1.5, # Base delay for exponential backoff
# Caching configuration
enable_caching=True,
cache_ttl=600, # Cache responses for 10 minutes
# Async rate limiting (async mode only)
enable_rate_limiting=True,
requests_per_second=10.0,
burst_limit=20,
# Advanced features
enable_metrics=True,
metrics_window_size=1000, # Track last 1000 requests
use_pydantic_models=False # Enable for type-safe models
)
api = CocApi('YOUR_API_TOKEN', config=config)
# Management methods
cache_stats = api.get_cache_stats()
metrics = api.get_metrics()
api.clear_cache()
api.clear_metrics()
```
## Asynchronous Usage
```python
import asyncio
from cocapi import CocApi, ApiConfig
async def main():
# Method 1: Automatic async mode with context manager (recommended)
async with CocApi('YOUR_API_TOKEN') as api:
clan = await api.clan_tag('#CLAN_TAG')
player = await api.players('#PLAYER_TAG')
# Method 2: Explicit async mode
api = CocApi('YOUR_API_TOKEN', async_mode=True)
async with api:
clan = await api.clan_tag('#CLAN_TAG')
# Method 3: With custom configuration
config = ApiConfig(timeout=30, enable_caching=True)
async with CocApi('YOUR_API_TOKEN', config=config) as api:
clan = await api.clan_tag('#CLAN_TAG')
# Run async code
asyncio.run(main())
```
## 🚀 Enterprise Features
### 📊 Metrics & Analytics
```python
from cocapi import CocApi, ApiConfig
# Enable metrics tracking
config = ApiConfig(enable_metrics=True, metrics_window_size=1000)
api = CocApi('YOUR_TOKEN', config=config)
# Get comprehensive metrics after API calls
metrics = api.get_metrics()
print(f"Total requests: {metrics['total_requests']}")
print(f"Average response time: {metrics['avg_response_time']:.2f}ms")
print(f"Cache hit rate: {metrics['cache_hit_rate']:.1%}")
print(f"Error rate: {metrics['error_rate']:.1%}")
```
### 🔌 Middleware System
```python
from cocapi import CocApi
from cocapi.middleware import add_user_agent_middleware, add_request_id_middleware
api = CocApi('YOUR_TOKEN')
# Add built-in middleware
api.add_request_middleware(add_user_agent_middleware("MyApp/1.0"))
api.add_request_middleware(add_request_id_middleware())
# Custom middleware
def add_custom_headers(url, headers, params):
headers['X-Client-Version'] = '3.0.0'
return url, headers, params
api.add_request_middleware(add_custom_headers)
```
### 🎯 Enhanced Caching
```python
from cocapi import CocApi, ApiConfig
config = ApiConfig(enable_caching=True, cache_ttl=900) # 15 minutes
api = CocApi('YOUR_TOKEN', config=config)
# Requests are cached automatically
clan1 = api.clan_tag('#CLAN_TAG') # Cache miss
clan2 = api.clan_tag('#CLAN_TAG') # Cache hit
# Cache statistics and management
stats = api.get_cache_stats()
api.clear_cache()
```
### ⚡ Async Rate Limiting
```python
from cocapi import CocApi, ApiConfig
import asyncio
async def high_throughput_example():
config = ApiConfig(
enable_rate_limiting=True,
requests_per_second=10.0,
burst_limit=20
)
async with CocApi('YOUR_TOKEN', config=config) as api:
# Concurrent requests with automatic rate limiting
clan_tags = ['#CLAN1', '#CLAN2', '#CLAN3']
tasks = [api.clan_tag(tag) for tag in clan_tags]
results = await asyncio.gather(*tasks)
asyncio.run(high_throughput_example())
```
## Pydantic Models (Optional)
For enhanced type safety and structured data validation, cocapi supports optional Pydantic models:
```python
from cocapi import CocApi, ApiConfig, Clan, Player
# Enable Pydantic models
config = ApiConfig(use_pydantic_models=True)
api = CocApi('YOUR_API_TOKEN', config=config)
# Get structured clan data
clan = api.clan_tag('#2PP') # Returns Clan model instead of dict
print(clan.name) # Type-safe attribute access
print(clan.clan_level) # IDE autocompletion support
print(clan.members) # Validated data structure
# Get structured player data
player = api.players('#PLAYER_TAG') # Returns Player model
print(player.town_hall_level) # Type-safe attributes
print(player.trophies)
print(player.clan.name if player.clan else "No clan")
# Works with async too
async def get_data():
config = ApiConfig(use_pydantic_models=True)
async with CocApi('YOUR_TOKEN', config=config) as api:
clan = await api.clan_tag('#TAG') # Returns Clan model
return clan.name
# Available models: Clan, Player, ClanMember, League, Achievement, etc.
# Import them: from cocapi import Clan, Player, ClanMember
```
### Benefits of Pydantic Models
- **Type Safety**: Catch errors at development time
- **IDE Support**: Full autocompletion and type hints
- **Data Validation**: Automatic validation of API responses
- **Clean Interface**: Object-oriented access to data
- **Documentation**: Self-documenting code with model schemas
- **Optional**: Zero impact if not used (lazy imports)
## Custom Endpoints 🚀
Use any new SuperCell endpoints immediately without waiting for library updates:
```python
from cocapi import CocApi
api = CocApi('YOUR_API_TOKEN')
# Call new endpoints directly
result = api.custom_endpoint('/new-endpoint')
result = api.custom_endpoint('/clans/search', {'name': 'my clan', 'limit': 10})
# With dynamic Pydantic models
result = api.custom_endpoint('/new-endpoint', use_dynamic_model=True)
print(result.some_field) # Type-safe access
# Async support
async with CocApi('YOUR_TOKEN') as api:
result = await api.custom_endpoint('/new-endpoint')
```
## Base URL Configuration 🌐
Modify base URL for testing, proxying, or adapting to API changes:
```python
from cocapi import CocApi, ApiConfig
api = CocApi('YOUR_TOKEN')
# Change base URL (requires force=True for safety)
api.set_base_url("https://api-staging.example.com/v1", force=True)
# Or set during initialization
config = ApiConfig(base_url="https://my-proxy.com/clash/v1")
api = CocApi('YOUR_TOKEN', config=config)
# Reset to official endpoint
api.reset_base_url()
```
## 📈 Performance Benefits
### Key Improvements
- **⚡ Intelligent Caching**: Up to 100% faster for repeated requests
- **🚀 Async Operations**: Handle dozens of concurrent requests efficiently
- **🔁 Smart Retry Logic**: Exponential backoff with configurable policies
- **📈 Monitoring**: Track error rates, response times, and cache performance
### Example Setup
```python
# High-performance configuration
config = ApiConfig(
enable_caching=True,
enable_metrics=True,
max_retries=3
)
api = CocApi('token', config=config)
# Async mode with concurrency
async with CocApi('token', config=config) as api:
clans = await asyncio.gather(*[
api.clan_tag(tag) for tag in clan_tags
])
```
## Migration Guide
### 🔄 Upgrading to v3.0.0 - Zero Breaking Changes!
cocapi 3.0.0 maintains 100% backward compatibility. Your existing code continues to work unchanged:
```python
# All existing patterns still work
from cocapi import CocApi
api = CocApi('YOUR_TOKEN') # ✅ Works
api = CocApi('YOUR_TOKEN', 60, True) # ✅ Works
clan = api.clan_tag('#CLAN_TAG') # ✅ Works
# To use new features, just add configuration:
config = ApiConfig(enable_caching=True, cache_ttl=300)
api = CocApi('YOUR_TOKEN', config=config)
```
## 🚀 What's New in v3.0.0
**Major enterprise features** while maintaining 100% backward compatibility:
- **📊 Enterprise Metrics**: Comprehensive API performance monitoring
- **🔌 Middleware System**: Pluggable request/response processing
- **⚡ Enhanced Async**: Rate limiting and improved concurrency
- **🚀 Custom Endpoints**: Future-proof support for new SuperCell endpoints
- **🎯 Type Safety**: Enhanced type hints and Pydantic model integration
- **🌐 Base URL Config**: Support for staging environments and proxies
### Installation
```bash
pip install --upgrade cocapi
# Or with Pydantic support:
pip install --upgrade 'cocapi[pydantic]'
```
## Previous Releases
**v2.2.x**: Pydantic models, enhanced type safety, async + Pydantic support
**v2.1.x**: Unified async support, intelligent caching, retry logic, enhanced configuration
## Full API Reference
All methods work identically in both sync and async modes - just use `await` when in async context!
---
## Clans
### Information about a Clan
```python
api.clan_tag(tag) #example tag "#9UOVJJ9J"
```
<details>
<summary>Click to view output</summary>
```text
{
"warLeague": {
"name": {},
"id": 0
},
"memberList": [
{
"league": {
"name": {},
"id": 0,
"iconUrls": {}
},
"tag": "string",
"name": "string",
"role": "string",
"expLevel": 0,
"clanRank": 0,
"previousClanRank": 0,
"donations": 0,
"donationsReceived": 0,
"trophies": 0,
"versusTrophies": 0
}
],
"isWarLogPublic": true,
"tag": "string",
"warFrequency": "string",
"clanLevel": 0,
"warWinStreak": 0,
"warWins": 0,
"warTies": 0,
"warLosses": 0,
"clanPoints": 0,
"clanVersusPoints": 0,
"requiredTrophies": 0,
"name": "string",
"location": {
"localizedName": "string",
"id": 0,
"name": "string",
"isCountry": true,
"countryCode": "string"
},
"type": "string",
"members": 0,
"labels": [
{
"name": {},
"id": 0,
"iconUrls": {}
}
],
"description": "string",
"badgeUrls": {}
}
```
</details>
#### Members Only
```python
api.clan_members(tag)
```
returns membersList information from api.clan_tag(tag) under "items" in dict
### War Log Information
```python
api.clan_war_log(tag)
```
<details>
<summary>Click to view output</summary>
```text
{items:
[
{
"clan": {
"destructionPercentage": {},
"tag": "string",
"name": "string",
"badgeUrls": {},
"clanLevel": 0,
"attacks": 0,
"stars": 0,
"expEarned": 0,
"members": [
{
"tag": "string",
"name": "string",
"mapPosition": 0,
"townhallLevel": 0,
"opponentAttacks": 0,
"bestOpponentAttack": {
"order": 0,
"attackerTag": "string",
"defenderTag": "string",
"stars": 0,
"destructionPercentage": 0
},
"attacks": [
{
"order": 0,
"attackerTag": "string",
"defenderTag": "string",
"stars": 0,
"destructionPercentage": 0
}
]
}
]
},
"teamSize": 0,
"opponent": {
"destructionPercentage": {},
"tag": "string",
"name": "string",
"badgeUrls": {},
"clanLevel": 0,
"attacks": 0,
"stars": 0,
"expEarned": 0,
"members": [
{
"tag": "string",
"name": "string",
"mapPosition": 0,
"townhallLevel": 0,
"opponentAttacks": 0,
"bestOpponentAttack": {
"order": 0,
"attackerTag": "string",
"defenderTag": "string",
"stars": 0,
"destructionPercentage": 0
},
"attacks": [
{
"order": 0,
"attackerTag": "string",
"defenderTag": "string",
"stars": 0,
"destructionPercentage": 0
}
]
}
]
},
"endTime": "string",
"result": "string"
}
],
"paging": {'cursors': {}}
}
```
</details>
### Current War Information
```python
api.clan_current_war(tag)
```
<details>
<summary>Click to view output</summary>
```text
{
"clan": {
"destructionPercentage": {},
"tag": "string",
"name": "string",
"badgeUrls": {},
"clanLevel": 0,
"attacks": 0,
"stars": 0,
"expEarned": 0,
"members": [
{
"tag": "string",
"name": "string",
"mapPosition": 0,
"townhallLevel": 0,
"opponentAttacks": 0,
"bestOpponentAttack": {
"order": 0,
"attackerTag": "string",
"defenderTag": "string",
"stars": 0,
"destructionPercentage": 0
},
"attacks": [
{
"order": 0,
"attackerTag": "string",
"defenderTag": "string",
"stars": 0,
"destructionPercentage": 0
}
]
}
]
},
"teamSize": 0,
"opponent": {
"destructionPercentage": {},
"tag": "string",
"name": "string",
"badgeUrls": {},
"clanLevel": 0,
"attacks": 0,
"stars": 0,
"expEarned": 0,
"members": [
{
"tag": "string",
"name": "string",
"mapPosition": 0,
"townhallLevel": 0,
"opponentAttacks": 0,
"bestOpponentAttack": {
"order": 0,
"attackerTag": "string",
"defenderTag": "string",
"stars": 0,
"destructionPercentage": 0
},
"attacks": [
{
"order": 0,
"attackerTag": "string",
"defenderTag": "string",
"stars": 0,
"destructionPercentage": 0
}
]
}
]
},
"startTime": "string",
"state": "string",
"endTime": "string",
"preparationStartTime": "string"
}
```
</details>
### Clan League Group Information
```python
api.clan_leaguegroup(tag)
```
<details>
<summary>Click to view output</summary>
```text
{
"tag": "string",
"state": "string",
"season": "string",
"clans": [
{
"tag": "string",
"clanLevel": 0,
"name": "string",
"members": [
{
"tag": "string",
"townHallLevel": 0,
"name": "string"
}
],
"badgeUrls": {}
}
],
"rounds": [
{
"warTags": [
"string"
]
}
]
}
```
</details>
### Clan Capital Raid Seasons
```python
api.clan_capitalraidseasons(tag)
```
Retrieve clan's capital raid seasons information
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"state": "string",
"startTime": "string",
"endTime": "string",
"capitalTotalLoot": 0,
"raidsCompleted": 0,
"totalAttacks": 0,
"enemyDistrictsDestroyed": 0,
"offensiveReward": 0,
"defensiveReward": 0,
"members": [
{
"tag": "string",
"name": "string",
"attacks": 0,
"attackLimit": 0,
"bonusAttackLimit": 0,
"capitalResourcesLooted": 0
}
]
}
],
"paging": {'cursors': {}}
}
```
</details>
### Warleague Information
```python
api.warleague(war_tag)
```
<details>
<summary>Click to view output</summary>
```text
{
"tag": "string",
"state": "string",
"season": "string",
"clans": [
{
"tag": "string",
"clanLevel": 0,
"name": "string",
"members": [
{
"tag": "string",
"townHallLevel": 0,
"name": "string"
}
],
"badgeUrls": {}
}
],
"rounds": [
{
"warTags": [
"string"
]
}
]
}
```
</details>
## Player
### Player information
```python
api.players(player_tag) #for example "#900PUCPV"
```
<details>
<summary>Click to view output</summary>
```text
{
"clan": {
"tag": "string",
"clanLevel": 0,
"name": "string",
"badgeUrls": {}
},
"league": {
"name": {},
"id": 0,
"iconUrls": {}
},
"townHallWeaponLevel": 0,
"versusBattleWins": 0,
"legendStatistics": {
"previousSeason": {
"trophies": 0,
"id": "string",
"rank": 0
},
"previousVersusSeason": {
"trophies": 0,
"id": "string",
"rank": 0
},
"bestVersusSeason": {
"trophies": 0,
"id": "string",
"rank": 0
},
"legendTrophies": 0,
"currentSeason": {
"trophies": 0,
"id": "string",
"rank": 0
},
"bestSeason": {
"trophies": 0,
"id": "string",
"rank": 0
}
},
"troops": [
{
"level": 0,
"name": {},
"maxLevel": 0,
"village": "string"
}
],
"heroes": [
{
"level": 0,
"name": {},
"maxLevel": 0,
"village": "string"
}
],
"spells": [
{
"level": 0,
"name": {},
"maxLevel": 0,
"village": "string"
}
],
"role": "string",
"attackWins": 0,
"defenseWins": 0,
"townHallLevel": 0,
"labels": [
{
"name": {},
"id": 0,
"iconUrls": {}
}
],
"tag": "string",
"name": "string",
"expLevel": 0,
"trophies": 0,
"bestTrophies": 0,
"donations": 0,
"donationsReceived": 0,
"builderHallLevel": 0,
"versusTrophies": 0,
"bestVersusTrophies": 0,
"warStars": 0,
"achievements": [
{
"stars": 0,
"value": 0,
"name": {},
"target": 0,
"info": {},
"completionInfo": {},
"village": "string"
}
],
"versusBattleWinCount": 0
}
```
</details>
## Locations
### All Locations Information
```python
api.location()
```
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"localizedName": "string",
"id": 0,
"name": "string",
"isCountry": true,
"countryCode": "string"
}
],
"paging": {'cursors': {}}
}
```
</details>
### Information for a Single Location
```python
api.location_id(location_tag) #for example "32000047"
```
returns the above information for a single location
### Top Clans in a Location
```python
api.location_id_clan_rank(location_tag)
```
Top 200 clans in a given location
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"clanLevel": 0,
"clanPoints": 0,
"location": {
"localizedName": "string",
"id": 0,
"name": "string",
"isCountry": true,
"countryCode": "string"
},
"members": 0,
"tag": "string",
"name": "string",
"rank": 0,
"previousRank": 0,
"badgeUrls": {}
}
],
"paging": {'cursors': {}}
}
```
</details>
### Top Players in a Location
```python
api.clan_leaguegroup(location_tag)
```
Top 200 players in a given location
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"clan": {
"tag": "string",
"name": "string",
"badgeUrls": {}
},
"league": {
"name": {},
"id": 0,
"iconUrls": {}
},
"attackWins": 0,
"defenseWins": 0,
"tag": "string",
"name": "string",
"expLevel": 0,
"rank": 0,
"previousRank": 0,
"trophies": 0
}
],
"paging": {'cursors': {}}
}
```
</details>
### Top Versus Clans in a Location
```python
api.location_clan_versus(location_tag)
```
Top 200 versus clans in a given location
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"clanPoints": 0,
"clanVersusPoints": 0
}
],
"paging": {'cursors': {}}
}
```
</details>
### Top Versus Players in a Location
```python
api.location_player_versus(location_tag)
```
Top 200 versus players in a given location
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"clan": {
"tag": "string",
"name": "string",
"badgeUrls": {}
},
"versusBattleWins": 0,
"tag": "string",
"name": "string",
"expLevel": 0,
"rank": 0,
"previousRank": 0,
"versusTrophies": 0
}
],
"paging": {'cursors': {}}
}
```
</details>
## Leagues
### List leagues
```python
api.league()
```
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"name": {},
"id": 0,
"iconUrls": {}
}
],
"paging": {'cursors': {}}
}
```
</details>
### League Information
```python
api.league_id(league_tag)
```
<details>
<summary>Click to view output</summary>
```text
{
"name": {},
"id": 0,
"iconUrls": {}
}
```
</details>
### List Season Leagues
```python
api.league_season(league_tag)
```
Information is available only for Legend League
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"id": "string"
}
],
"paging": {'cursors': {}}
}
```
</details>
### League Season Ranking
```python
api.league_season_id(league_tag, season_tag)
```
Information is available only for Legend League
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"clan": {
"tag": "string",
"name": "string",
"badgeUrls": {}
},
"league": {
"name": {},
"id": 0,
"iconUrls": {}
},
"attackWins": 0,
"defenseWins": 0,
"tag": "string",
"name": "string",
"expLevel": 0,
"rank": 0,
"previousRank": 0,
"trophies": 0
}
],
"paging": {'cursors': {}}
}
```
</details>
### List Capital Leagues
```python
api.capitalleagues()
```
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"name": {},
"id": 0,
"iconUrls": {}
}
],
"paging": {'cursors': {}}
}
```
</details>
### Capital League Information
```python
api.capitalleagues_id(league_id)
```
<details>
<summary>Click to view output</summary>
```text
{
"name": {},
"id": 0,
"iconUrls": {}
}
```
</details>
### List Builder Base Leagues
```python
api.builderbaseleagues()
```
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"name": {},
"id": 0,
"iconUrls": {}
}
],
"paging": {'cursors': {}}
}
```
</details>
### Builder Base League Information
```python
api.builderbaseleagues_id(league_id)
```
<details>
<summary>Click to view output</summary>
```text
{
"name": {},
"id": 0,
"iconUrls": {}
}
```
</details>
### List War Leagues
```python
api.warleagues()
```
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"name": {},
"id": 0,
"iconUrls": {}
}
],
"paging": {'cursors': {}}
}
```
</details>
### War League Information
```python
api.warleagues_id(league_id)
```
<details>
<summary>Click to view output</summary>
```text
{
"name": {},
"id": 0,
"iconUrls": {}
}
```
</details>
## Gold Pass
### Current Gold Pass Season
```python
api.goldpass_seasons_current()
```
Get information about the current gold pass season
<details>
<summary>Click to view output</summary>
```text
{
"startTime": "string",
"endTime": "string"
}
```
</details>
## Labels
### List Clan Labels
```python
api.labels_clans()
```
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"name": {},
"id": 0,
"iconUrls": {}
}
],
"paging": {'cursors': {}}
}
```
</details>
### List Player Labels
```python
api.labels_players()
```
<details>
<summary>Click to view output</summary>
```text
{"items":
[
{
"name": {},
"id": 0,
"iconUrls": {}
}
],
"paging": {'cursors': {}}
}
```
</details>
## Credits
- [All Contributors](../../contributors)
*Note versions below 2.0.0 are not supported anymore*
*DISCLAIMER: cocapi is not affiliated with SuperCell©.
Raw data
{
"_id": null,
"home_page": null,
"name": "cocapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7.2",
"maintainer_email": null,
"keywords": "api, clans, clash, supercell, wrapper",
"author": null,
"author_email": "Tony Benoy <me@tonybenoy.com>",
"download_url": "https://files.pythonhosted.org/packages/7d/87/1a150dcf61bf716ecb8b10f19596eebf3c3a84121e53f56de46cb79a7559/cocapi-3.0.1.tar.gz",
"platform": null,
"description": "<p>\n <a href=\"https://github.com/tonybenoy/cocapi/actions\">\n <img src=\"https://github.com/tonybenoy/cocapi/workflows/CI/badge.svg\" alt=\"CI Status\" height=\"20\">\n </a>\n <a href=\"https://pypi.org/project/cocapi/\"><img src=\"https://img.shields.io/pypi/v/cocapi\" alt=\"Pypi version\" height=\"21\"></a>\n</p>\n<p>\n <a href=\"https://www.python.org/downloads/\"><img src=\"https://img.shields.io/badge/python-3.7+-blue.svg\" alt=\"Python version\" height=\"17\"></a>\n <a href=\"https://github.com/tonybenoy/cocapi/blob/master/LICENSE\"><img src=\"https://img.shields.io/github/license/tonybenoy/cocapi\" alt=\"License\" height=\"17\"></a>\n <a href=\"https://github.com/astral-sh/ruff\">\n <img src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\" alt=\"Ruff\" height=\"17\">\n </a>\n</p>\n\n# ClashOfClansAPI v3.0.0\n\nA high-performance Python wrapper for SuperCell's Clash of Clans API with enterprise-grade features including async support, response caching, retry logic, middleware system, and comprehensive metrics.\n\n**\ud83c\udfaf Complete API Coverage**: All 22 official endpoints implemented \n**\u26a1 High Performance**: Async support with intelligent caching and rate limiting \n**\ud83d\udd04 100% Backward Compatible**: Drop-in replacement for existing code \n**\ud83d\udee1\ufe0f Production Ready**: Retry logic, middleware pipeline, metrics tracking, and comprehensive error handling \n**\ud83d\ude80 Future-Proof**: Custom endpoint support and dynamic Pydantic models\n\nGet Token from [https://developer.clashofclans.com/](https://developer.clashofclans.com/)\n\n## \u2728 Key Features\n\n- **\ud83d\udd04 Sync & Async Support**: Same API works for both sync and async\n- **\ud83d\ude80 Custom Endpoints**: Future-proof with any new SuperCell endpoints \n- **\ud83d\udcbe Intelligent Caching**: Response caching with configurable TTL and statistics\n- **\ud83d\udd01 Smart Retry Logic**: Exponential backoff with configurable retry policies\n- **\u26a1 Rate Limiting**: Built-in protection against API rate limits (async mode)\n- **\ud83d\udee1\ufe0f Comprehensive Error Handling**: Detailed error messages and types\n- **\ud83d\udcca Metrics & Analytics**: Request performance tracking and insights\n- **\ud83d\udd0c Middleware System**: Pluggable request/response processing pipeline\n- **\ud83c\udfaf Type Safety**: Complete type hints and optional Pydantic models\n- **\ud83c\udf10 Base URL Configuration**: Support for proxies and testing environments\n- **\ud83d\udd04 100% Backward Compatible**: Drop-in replacement for existing code\n\n# Install\n\n```bash\n# Standard installation (dict responses)\npip install cocapi\n\n# With optional Pydantic models support\npip install 'cocapi[pydantic]'\n```\n\n\n# Usage Examples\n\n## Basic Synchronous Usage (Backward Compatible)\n\n```python\nfrom cocapi import CocApi\n\ntoken = 'YOUR_API_TOKEN'\ntimeout = 60 # requests timeout\n\n# Basic initialization (same as before)\napi = CocApi(token, timeout)\n\n# With status codes (same as before)\napi = CocApi(token, timeout, status_code=True)\n```\n\n## Advanced Configuration\n\n```python\nfrom cocapi import CocApi, ApiConfig\n\n# Enterprise-grade configuration\nconfig = ApiConfig(\n # Performance settings\n timeout=30,\n max_retries=5,\n retry_delay=1.5, # Base delay for exponential backoff\n \n # Caching configuration \n enable_caching=True,\n cache_ttl=600, # Cache responses for 10 minutes\n \n # Async rate limiting (async mode only)\n enable_rate_limiting=True,\n requests_per_second=10.0,\n burst_limit=20,\n \n # Advanced features\n enable_metrics=True,\n metrics_window_size=1000, # Track last 1000 requests\n use_pydantic_models=False # Enable for type-safe models\n)\n\napi = CocApi('YOUR_API_TOKEN', config=config)\n\n# Management methods\ncache_stats = api.get_cache_stats()\nmetrics = api.get_metrics()\napi.clear_cache()\napi.clear_metrics()\n```\n\n## Asynchronous Usage\n\n```python\nimport asyncio\nfrom cocapi import CocApi, ApiConfig\n\nasync def main():\n # Method 1: Automatic async mode with context manager (recommended)\n async with CocApi('YOUR_API_TOKEN') as api:\n clan = await api.clan_tag('#CLAN_TAG')\n player = await api.players('#PLAYER_TAG')\n \n # Method 2: Explicit async mode\n api = CocApi('YOUR_API_TOKEN', async_mode=True)\n async with api:\n clan = await api.clan_tag('#CLAN_TAG')\n \n # Method 3: With custom configuration\n config = ApiConfig(timeout=30, enable_caching=True)\n async with CocApi('YOUR_API_TOKEN', config=config) as api:\n clan = await api.clan_tag('#CLAN_TAG')\n\n# Run async code\nasyncio.run(main())\n```\n\n## \ud83d\ude80 Enterprise Features\n\n### \ud83d\udcca Metrics & Analytics\n\n```python\nfrom cocapi import CocApi, ApiConfig\n\n# Enable metrics tracking\nconfig = ApiConfig(enable_metrics=True, metrics_window_size=1000)\napi = CocApi('YOUR_TOKEN', config=config)\n\n# Get comprehensive metrics after API calls\nmetrics = api.get_metrics()\nprint(f\"Total requests: {metrics['total_requests']}\")\nprint(f\"Average response time: {metrics['avg_response_time']:.2f}ms\")\nprint(f\"Cache hit rate: {metrics['cache_hit_rate']:.1%}\")\nprint(f\"Error rate: {metrics['error_rate']:.1%}\")\n```\n\n### \ud83d\udd0c Middleware System\n\n```python\nfrom cocapi import CocApi\nfrom cocapi.middleware import add_user_agent_middleware, add_request_id_middleware\n\napi = CocApi('YOUR_TOKEN')\n\n# Add built-in middleware\napi.add_request_middleware(add_user_agent_middleware(\"MyApp/1.0\"))\napi.add_request_middleware(add_request_id_middleware())\n\n# Custom middleware\ndef add_custom_headers(url, headers, params):\n headers['X-Client-Version'] = '3.0.0'\n return url, headers, params\n\napi.add_request_middleware(add_custom_headers)\n```\n\n### \ud83c\udfaf Enhanced Caching\n\n```python\nfrom cocapi import CocApi, ApiConfig\n\nconfig = ApiConfig(enable_caching=True, cache_ttl=900) # 15 minutes\napi = CocApi('YOUR_TOKEN', config=config)\n\n# Requests are cached automatically\nclan1 = api.clan_tag('#CLAN_TAG') # Cache miss\nclan2 = api.clan_tag('#CLAN_TAG') # Cache hit\n\n# Cache statistics and management\nstats = api.get_cache_stats()\napi.clear_cache()\n```\n\n### \u26a1 Async Rate Limiting\n\n```python\nfrom cocapi import CocApi, ApiConfig\nimport asyncio\n\nasync def high_throughput_example():\n config = ApiConfig(\n enable_rate_limiting=True,\n requests_per_second=10.0,\n burst_limit=20\n )\n \n async with CocApi('YOUR_TOKEN', config=config) as api:\n # Concurrent requests with automatic rate limiting\n clan_tags = ['#CLAN1', '#CLAN2', '#CLAN3']\n tasks = [api.clan_tag(tag) for tag in clan_tags]\n results = await asyncio.gather(*tasks)\n\nasyncio.run(high_throughput_example())\n```\n\n## Pydantic Models (Optional)\n\nFor enhanced type safety and structured data validation, cocapi supports optional Pydantic models:\n\n```python\nfrom cocapi import CocApi, ApiConfig, Clan, Player\n\n# Enable Pydantic models\nconfig = ApiConfig(use_pydantic_models=True)\napi = CocApi('YOUR_API_TOKEN', config=config)\n\n# Get structured clan data\nclan = api.clan_tag('#2PP') # Returns Clan model instead of dict\nprint(clan.name) # Type-safe attribute access\nprint(clan.clan_level) # IDE autocompletion support\nprint(clan.members) # Validated data structure\n\n# Get structured player data \nplayer = api.players('#PLAYER_TAG') # Returns Player model\nprint(player.town_hall_level) # Type-safe attributes\nprint(player.trophies)\nprint(player.clan.name if player.clan else \"No clan\")\n\n# Works with async too\nasync def get_data():\n config = ApiConfig(use_pydantic_models=True)\n async with CocApi('YOUR_TOKEN', config=config) as api:\n clan = await api.clan_tag('#TAG') # Returns Clan model\n return clan.name\n\n# Available models: Clan, Player, ClanMember, League, Achievement, etc.\n# Import them: from cocapi import Clan, Player, ClanMember\n```\n\n### Benefits of Pydantic Models\n\n- **Type Safety**: Catch errors at development time\n- **IDE Support**: Full autocompletion and type hints\n- **Data Validation**: Automatic validation of API responses \n- **Clean Interface**: Object-oriented access to data\n- **Documentation**: Self-documenting code with model schemas\n- **Optional**: Zero impact if not used (lazy imports)\n\n## Custom Endpoints \ud83d\ude80\n\nUse any new SuperCell endpoints immediately without waiting for library updates:\n\n```python\nfrom cocapi import CocApi\n\napi = CocApi('YOUR_API_TOKEN')\n\n# Call new endpoints directly\nresult = api.custom_endpoint('/new-endpoint')\nresult = api.custom_endpoint('/clans/search', {'name': 'my clan', 'limit': 10})\n\n# With dynamic Pydantic models\nresult = api.custom_endpoint('/new-endpoint', use_dynamic_model=True)\nprint(result.some_field) # Type-safe access\n\n# Async support\nasync with CocApi('YOUR_TOKEN') as api:\n result = await api.custom_endpoint('/new-endpoint')\n```\n\n## Base URL Configuration \ud83c\udf10\n\nModify base URL for testing, proxying, or adapting to API changes:\n\n```python\nfrom cocapi import CocApi, ApiConfig\n\napi = CocApi('YOUR_TOKEN')\n\n# Change base URL (requires force=True for safety)\napi.set_base_url(\"https://api-staging.example.com/v1\", force=True)\n\n# Or set during initialization\nconfig = ApiConfig(base_url=\"https://my-proxy.com/clash/v1\")\napi = CocApi('YOUR_TOKEN', config=config)\n\n# Reset to official endpoint\napi.reset_base_url()\n```\n\n## \ud83d\udcc8 Performance Benefits\n\n### Key Improvements\n- **\u26a1 Intelligent Caching**: Up to 100% faster for repeated requests\n- **\ud83d\ude80 Async Operations**: Handle dozens of concurrent requests efficiently\n- **\ud83d\udd01 Smart Retry Logic**: Exponential backoff with configurable policies\n- **\ud83d\udcc8 Monitoring**: Track error rates, response times, and cache performance\n\n### Example Setup\n```python\n# High-performance configuration\nconfig = ApiConfig(\n enable_caching=True,\n enable_metrics=True,\n max_retries=3\n)\n\napi = CocApi('token', config=config)\n\n# Async mode with concurrency\nasync with CocApi('token', config=config) as api:\n clans = await asyncio.gather(*[\n api.clan_tag(tag) for tag in clan_tags\n ])\n```\n\n## Migration Guide \n\n### \ud83d\udd04 Upgrading to v3.0.0 - Zero Breaking Changes!\n\ncocapi 3.0.0 maintains 100% backward compatibility. Your existing code continues to work unchanged:\n\n```python\n# All existing patterns still work\nfrom cocapi import CocApi\n\napi = CocApi('YOUR_TOKEN') # \u2705 Works\napi = CocApi('YOUR_TOKEN', 60, True) # \u2705 Works\nclan = api.clan_tag('#CLAN_TAG') # \u2705 Works\n\n# To use new features, just add configuration:\nconfig = ApiConfig(enable_caching=True, cache_ttl=300)\napi = CocApi('YOUR_TOKEN', config=config)\n```\n\n## \ud83d\ude80 What's New in v3.0.0\n\n**Major enterprise features** while maintaining 100% backward compatibility:\n\n- **\ud83d\udcca Enterprise Metrics**: Comprehensive API performance monitoring\n- **\ud83d\udd0c Middleware System**: Pluggable request/response processing \n- **\u26a1 Enhanced Async**: Rate limiting and improved concurrency\n- **\ud83d\ude80 Custom Endpoints**: Future-proof support for new SuperCell endpoints\n- **\ud83c\udfaf Type Safety**: Enhanced type hints and Pydantic model integration\n- **\ud83c\udf10 Base URL Config**: Support for staging environments and proxies\n\n### Installation\n```bash\npip install --upgrade cocapi\n# Or with Pydantic support:\npip install --upgrade 'cocapi[pydantic]'\n```\n\n## Previous Releases\n\n**v2.2.x**: Pydantic models, enhanced type safety, async + Pydantic support \n**v2.1.x**: Unified async support, intelligent caching, retry logic, enhanced configuration\n\n## Full API Reference\n\nAll methods work identically in both sync and async modes - just use `await` when in async context!\n\n---\n\n## Clans\n\n### Information about a Clan\n```python\napi.clan_tag(tag) #example tag \"#9UOVJJ9J\"\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"warLeague\": {\n \"name\": {},\n \"id\": 0\n },\n \"memberList\": [\n {\n \"league\": {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n },\n \"tag\": \"string\",\n \"name\": \"string\",\n \"role\": \"string\",\n \"expLevel\": 0,\n \"clanRank\": 0,\n \"previousClanRank\": 0,\n \"donations\": 0,\n \"donationsReceived\": 0,\n \"trophies\": 0,\n \"versusTrophies\": 0\n }\n ],\n \"isWarLogPublic\": true,\n \"tag\": \"string\",\n \"warFrequency\": \"string\",\n \"clanLevel\": 0,\n \"warWinStreak\": 0,\n \"warWins\": 0,\n \"warTies\": 0,\n \"warLosses\": 0,\n \"clanPoints\": 0,\n \"clanVersusPoints\": 0,\n \"requiredTrophies\": 0,\n \"name\": \"string\",\n \"location\": {\n \"localizedName\": \"string\",\n \"id\": 0,\n \"name\": \"string\",\n \"isCountry\": true,\n \"countryCode\": \"string\"\n },\n \"type\": \"string\",\n \"members\": 0,\n \"labels\": [\n {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n }\n ],\n \"description\": \"string\",\n \"badgeUrls\": {}\n}\n```\n</details>\n\n#### Members Only\n```python\napi.clan_members(tag)\n```\nreturns membersList information from api.clan_tag(tag) under \"items\" in dict\n\n### War Log Information\n```python\napi.clan_war_log(tag)\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{items:\n[\n {\n \"clan\": {\n \"destructionPercentage\": {},\n \"tag\": \"string\",\n \"name\": \"string\",\n \"badgeUrls\": {},\n \"clanLevel\": 0,\n \"attacks\": 0,\n \"stars\": 0,\n \"expEarned\": 0,\n \"members\": [\n {\n \"tag\": \"string\",\n \"name\": \"string\",\n \"mapPosition\": 0,\n \"townhallLevel\": 0,\n \"opponentAttacks\": 0,\n \"bestOpponentAttack\": {\n \"order\": 0,\n \"attackerTag\": \"string\",\n \"defenderTag\": \"string\",\n \"stars\": 0,\n \"destructionPercentage\": 0\n },\n \"attacks\": [\n {\n \"order\": 0,\n \"attackerTag\": \"string\",\n \"defenderTag\": \"string\",\n \"stars\": 0,\n \"destructionPercentage\": 0\n }\n ]\n }\n ]\n },\n \"teamSize\": 0,\n \"opponent\": {\n \"destructionPercentage\": {},\n \"tag\": \"string\",\n \"name\": \"string\",\n \"badgeUrls\": {},\n \"clanLevel\": 0,\n \"attacks\": 0,\n \"stars\": 0,\n \"expEarned\": 0,\n \"members\": [\n {\n \"tag\": \"string\",\n \"name\": \"string\",\n \"mapPosition\": 0,\n \"townhallLevel\": 0,\n \"opponentAttacks\": 0,\n \"bestOpponentAttack\": {\n \"order\": 0,\n \"attackerTag\": \"string\",\n \"defenderTag\": \"string\",\n \"stars\": 0,\n \"destructionPercentage\": 0\n },\n \"attacks\": [\n {\n \"order\": 0,\n \"attackerTag\": \"string\",\n \"defenderTag\": \"string\",\n \"stars\": 0,\n \"destructionPercentage\": 0\n }\n ]\n }\n ]\n },\n \"endTime\": \"string\",\n \"result\": \"string\"\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n### Current War Information\n```python\napi.clan_current_war(tag)\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"clan\": {\n \"destructionPercentage\": {},\n \"tag\": \"string\",\n \"name\": \"string\",\n \"badgeUrls\": {},\n \"clanLevel\": 0,\n \"attacks\": 0,\n \"stars\": 0,\n \"expEarned\": 0,\n \"members\": [\n {\n \"tag\": \"string\",\n \"name\": \"string\",\n \"mapPosition\": 0,\n \"townhallLevel\": 0,\n \"opponentAttacks\": 0,\n \"bestOpponentAttack\": {\n \"order\": 0,\n \"attackerTag\": \"string\",\n \"defenderTag\": \"string\",\n \"stars\": 0,\n \"destructionPercentage\": 0\n },\n \"attacks\": [\n {\n \"order\": 0,\n \"attackerTag\": \"string\",\n \"defenderTag\": \"string\",\n \"stars\": 0,\n \"destructionPercentage\": 0\n }\n ]\n }\n ]\n },\n \"teamSize\": 0,\n \"opponent\": {\n \"destructionPercentage\": {},\n \"tag\": \"string\",\n \"name\": \"string\",\n \"badgeUrls\": {},\n \"clanLevel\": 0,\n \"attacks\": 0,\n \"stars\": 0,\n \"expEarned\": 0,\n \"members\": [\n {\n \"tag\": \"string\",\n \"name\": \"string\",\n \"mapPosition\": 0,\n \"townhallLevel\": 0,\n \"opponentAttacks\": 0,\n \"bestOpponentAttack\": {\n \"order\": 0,\n \"attackerTag\": \"string\",\n \"defenderTag\": \"string\",\n \"stars\": 0,\n \"destructionPercentage\": 0\n },\n \"attacks\": [\n {\n \"order\": 0,\n \"attackerTag\": \"string\",\n \"defenderTag\": \"string\",\n \"stars\": 0,\n \"destructionPercentage\": 0\n }\n ]\n }\n ]\n },\n \"startTime\": \"string\",\n \"state\": \"string\",\n \"endTime\": \"string\",\n \"preparationStartTime\": \"string\"\n}\n```\n</details>\n\n### Clan League Group Information\n```python\napi.clan_leaguegroup(tag)\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"tag\": \"string\",\n \"state\": \"string\",\n \"season\": \"string\",\n \"clans\": [\n {\n \"tag\": \"string\",\n \"clanLevel\": 0,\n \"name\": \"string\",\n \"members\": [\n {\n \"tag\": \"string\",\n \"townHallLevel\": 0,\n \"name\": \"string\"\n }\n ],\n \"badgeUrls\": {}\n }\n ],\n \"rounds\": [\n {\n \"warTags\": [\n \"string\"\n ]\n }\n ]\n}\n```\n</details>\n\n### Clan Capital Raid Seasons\n```python\napi.clan_capitalraidseasons(tag)\n```\nRetrieve clan's capital raid seasons information\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"state\": \"string\",\n \"startTime\": \"string\", \n \"endTime\": \"string\",\n \"capitalTotalLoot\": 0,\n \"raidsCompleted\": 0,\n \"totalAttacks\": 0,\n \"enemyDistrictsDestroyed\": 0,\n \"offensiveReward\": 0,\n \"defensiveReward\": 0,\n \"members\": [\n {\n \"tag\": \"string\",\n \"name\": \"string\",\n \"attacks\": 0,\n \"attackLimit\": 0,\n \"bonusAttackLimit\": 0,\n \"capitalResourcesLooted\": 0\n }\n ]\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n### Warleague Information\n```python\napi.warleague(war_tag)\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"tag\": \"string\",\n \"state\": \"string\",\n \"season\": \"string\",\n \"clans\": [\n {\n \"tag\": \"string\",\n \"clanLevel\": 0,\n \"name\": \"string\",\n \"members\": [\n {\n \"tag\": \"string\",\n \"townHallLevel\": 0,\n \"name\": \"string\"\n }\n ],\n \"badgeUrls\": {}\n }\n ],\n \"rounds\": [\n {\n \"warTags\": [\n \"string\"\n ]\n }\n ]\n}\n```\n</details>\n\n\n\n\n## Player\n\n### Player information\n```python\napi.players(player_tag) #for example \"#900PUCPV\"\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"clan\": {\n \"tag\": \"string\",\n \"clanLevel\": 0,\n \"name\": \"string\",\n \"badgeUrls\": {}\n },\n \"league\": {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n },\n \"townHallWeaponLevel\": 0,\n \"versusBattleWins\": 0,\n \"legendStatistics\": {\n \"previousSeason\": {\n \"trophies\": 0,\n \"id\": \"string\",\n \"rank\": 0\n },\n \"previousVersusSeason\": {\n \"trophies\": 0,\n \"id\": \"string\",\n \"rank\": 0\n },\n \"bestVersusSeason\": {\n \"trophies\": 0,\n \"id\": \"string\",\n \"rank\": 0\n },\n \"legendTrophies\": 0,\n \"currentSeason\": {\n \"trophies\": 0,\n \"id\": \"string\",\n \"rank\": 0\n },\n \"bestSeason\": {\n \"trophies\": 0,\n \"id\": \"string\",\n \"rank\": 0\n }\n },\n \"troops\": [\n {\n \"level\": 0,\n \"name\": {},\n \"maxLevel\": 0,\n \"village\": \"string\"\n }\n ],\n \"heroes\": [\n {\n \"level\": 0,\n \"name\": {},\n \"maxLevel\": 0,\n \"village\": \"string\"\n }\n ],\n \"spells\": [\n {\n \"level\": 0,\n \"name\": {},\n \"maxLevel\": 0,\n \"village\": \"string\"\n }\n ],\n \"role\": \"string\",\n \"attackWins\": 0,\n \"defenseWins\": 0,\n \"townHallLevel\": 0,\n \"labels\": [\n {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n }\n ],\n \"tag\": \"string\",\n \"name\": \"string\",\n \"expLevel\": 0,\n \"trophies\": 0,\n \"bestTrophies\": 0,\n \"donations\": 0,\n \"donationsReceived\": 0,\n \"builderHallLevel\": 0,\n \"versusTrophies\": 0,\n \"bestVersusTrophies\": 0,\n \"warStars\": 0,\n \"achievements\": [\n {\n \"stars\": 0,\n \"value\": 0,\n \"name\": {},\n \"target\": 0,\n \"info\": {},\n \"completionInfo\": {},\n \"village\": \"string\"\n }\n ],\n \"versusBattleWinCount\": 0\n}\n```\n</details>\n\n\n\n\n## Locations\n\n### All Locations Information\n```python\napi.location()\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"localizedName\": \"string\",\n \"id\": 0,\n \"name\": \"string\",\n \"isCountry\": true,\n \"countryCode\": \"string\"\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n### Information for a Single Location\n```python\napi.location_id(location_tag) #for example \"32000047\"\n```\n\nreturns the above information for a single location\n\n### Top Clans in a Location\n```python\napi.location_id_clan_rank(location_tag)\n```\nTop 200 clans in a given location\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"clanLevel\": 0,\n \"clanPoints\": 0,\n \"location\": {\n \"localizedName\": \"string\",\n \"id\": 0,\n \"name\": \"string\",\n \"isCountry\": true,\n \"countryCode\": \"string\"\n },\n \"members\": 0,\n \"tag\": \"string\",\n \"name\": \"string\",\n \"rank\": 0,\n \"previousRank\": 0,\n \"badgeUrls\": {}\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n### Top Players in a Location\n```python\napi.clan_leaguegroup(location_tag)\n```\nTop 200 players in a given location\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"clan\": {\n \"tag\": \"string\",\n \"name\": \"string\",\n \"badgeUrls\": {}\n },\n \"league\": {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n },\n \"attackWins\": 0,\n \"defenseWins\": 0,\n \"tag\": \"string\",\n \"name\": \"string\",\n \"expLevel\": 0,\n \"rank\": 0,\n \"previousRank\": 0,\n \"trophies\": 0\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n\n### Top Versus Clans in a Location\n```python\napi.location_clan_versus(location_tag)\n```\nTop 200 versus clans in a given location\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"clanPoints\": 0,\n \"clanVersusPoints\": 0\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n\n### Top Versus Players in a Location\n```python\napi.location_player_versus(location_tag)\n```\nTop 200 versus players in a given location\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"clan\": {\n \"tag\": \"string\",\n \"name\": \"string\",\n \"badgeUrls\": {}\n },\n \"versusBattleWins\": 0,\n \"tag\": \"string\",\n \"name\": \"string\",\n \"expLevel\": 0,\n \"rank\": 0,\n \"previousRank\": 0,\n \"versusTrophies\": 0\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n\n\n\n## Leagues\n\n### List leagues\n```python\napi.league()\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n\n### League Information\n```python\napi.league_id(league_tag)\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n}\n```\n</details>\n\n\n### List Season Leagues\n```python\napi.league_season(league_tag)\n```\nInformation is available only for Legend League\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"id\": \"string\"\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n\n### League Season Ranking\n```python\napi.league_season_id(league_tag, season_tag)\n```\nInformation is available only for Legend League\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"clan\": {\n \"tag\": \"string\",\n \"name\": \"string\",\n \"badgeUrls\": {}\n },\n \"league\": {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n },\n \"attackWins\": 0,\n \"defenseWins\": 0,\n \"tag\": \"string\",\n \"name\": \"string\",\n \"expLevel\": 0,\n \"rank\": 0,\n \"previousRank\": 0,\n \"trophies\": 0\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n### List Capital Leagues\n```python\napi.capitalleagues()\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n### Capital League Information\n```python\napi.capitalleagues_id(league_id)\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n}\n```\n</details>\n\n### List Builder Base Leagues\n```python\napi.builderbaseleagues()\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n### Builder Base League Information\n```python\napi.builderbaseleagues_id(league_id)\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n}\n```\n</details>\n\n### List War Leagues\n```python\napi.warleagues()\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n### War League Information\n```python\napi.warleagues_id(league_id)\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n}\n```\n</details>\n\n\n\n\n## Gold Pass\n\n### Current Gold Pass Season\n```python\napi.goldpass_seasons_current()\n```\nGet information about the current gold pass season\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\n \"startTime\": \"string\",\n \"endTime\": \"string\" \n}\n```\n</details>\n\n\n## Labels\n\n### List Clan Labels\n```python\napi.labels_clans()\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n\n### List Player Labels\n```python\napi.labels_players()\n```\n<details>\n <summary>Click to view output</summary>\n\n```text\n{\"items\":\n[\n {\n \"name\": {},\n \"id\": 0,\n \"iconUrls\": {}\n }\n],\n\"paging\": {'cursors': {}}\n}\n```\n</details>\n\n\n## Credits\n- [All Contributors](../../contributors)\n\n*Note versions below 2.0.0 are not supported anymore*\n\n*DISCLAIMER: cocapi is not affiliated with SuperCell\u00a9.\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "A python wrapper around clash of clans api",
"version": "3.0.1",
"project_urls": {
"Homepage": "https://github.com/tonybenoy/cocapi",
"Issues": "https://github.com/tonybenoy/cocapi/issues",
"Repository": "https://github.com/tonybenoy/cocapi"
},
"split_keywords": [
"api",
" clans",
" clash",
" supercell",
" wrapper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8f3cf86e1bfb8541823b4872f2f999da4578406e486a7551fb3e928d0ec85f44",
"md5": "ee3672759d15dc3d6cccde07d5892416",
"sha256": "01417a89a7f5b730ecf3183f80acacd0e9b7b37a4c85882dadbe2c83a38d4bfb"
},
"downloads": -1,
"filename": "cocapi-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee3672759d15dc3d6cccde07d5892416",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.2",
"size": 39778,
"upload_time": "2025-08-10T08:28:09",
"upload_time_iso_8601": "2025-08-10T08:28:09.967152Z",
"url": "https://files.pythonhosted.org/packages/8f/3c/f86e1bfb8541823b4872f2f999da4578406e486a7551fb3e928d0ec85f44/cocapi-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d871a150dcf61bf716ecb8b10f19596eebf3c3a84121e53f56de46cb79a7559",
"md5": "e8749c36dd8a7bcb4620fc5e7f7c293f",
"sha256": "5b2130c7a4c9e2ac1e5f355eadc81c3598e963868fc9254caa16d627e3ba91de"
},
"downloads": -1,
"filename": "cocapi-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "e8749c36dd8a7bcb4620fc5e7f7c293f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.2",
"size": 104421,
"upload_time": "2025-08-10T08:28:11",
"upload_time_iso_8601": "2025-08-10T08:28:11.628861Z",
"url": "https://files.pythonhosted.org/packages/7d/87/1a150dcf61bf716ecb8b10f19596eebf3c3a84121e53f56de46cb79a7559/cocapi-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 08:28:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tonybenoy",
"github_project": "cocapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cocapi"
}
