Skip to content

api_methods

api_methods

All Clash of Clans API endpoint methods

ApiMethods

Mixin class containing all COC API endpoint methods

clan_tag 

clan_tag(
    tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get clan information

Source code in cocapi/api_methods.py 
55
56
57
58
59
60
61
62
63
def clan_tag(
    self, tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get clan information"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM

    tag = clean_tag(tag)
    return self._api_response(f"/clans/%23{urllib.parse.quote(tag)}", params)

clan_members 

clan_members(
    clan_tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get clan members

Source code in cocapi/api_methods.py 
65
66
67
68
69
70
71
72
73
74
75
def clan_members(
    self, clan_tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get clan members"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM

    clan_tag = clean_tag(clan_tag)
    return self._api_response(
        f"/clans/%23{urllib.parse.quote(clan_tag)}/members", params
    )

clan_current_war 

clan_current_war(
    clan_tag: str,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get current clan war information

Source code in cocapi/api_methods.py 
77
78
79
80
81
82
83
84
def clan_current_war(
    self, clan_tag: str
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get current clan war information"""
    clan_tag = clean_tag(clan_tag)
    return self._api_response(
        f"/clans/%23{urllib.parse.quote(clan_tag)}/currentwar"
    )

clan_war_log 

clan_war_log(
    clan_tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get clan war log

Source code in cocapi/api_methods.py 
86
87
88
89
90
91
92
93
94
95
96
def clan_war_log(
    self, clan_tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get clan war log"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM

    clan_tag = clean_tag(clan_tag)
    return self._api_response(
        f"/clans/%23{urllib.parse.quote(clan_tag)}/warlog", params
    )

clan_leaguegroup 

clan_leaguegroup(
    clan_tag: str,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get clan's current clan war league group

Source code in cocapi/api_methods.py 
 98
 99
100
101
102
103
104
105
def clan_leaguegroup(
    self, clan_tag: str
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get clan's current clan war league group"""
    clan_tag = clean_tag(clan_tag)
    return self._api_response(
        f"/clans/%23{urllib.parse.quote(clan_tag)}/currentwar/leaguegroup"
    )

clan_capitalraidseasons 

clan_capitalraidseasons(
    clan_tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get clan capital raid seasons

Source code in cocapi/api_methods.py 
107
108
109
110
111
112
113
114
115
116
117
def clan_capitalraidseasons(
    self, clan_tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get clan capital raid seasons"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM

    clan_tag = clean_tag(clan_tag)
    return self._api_response(
        f"/clans/%23{urllib.parse.quote(clan_tag)}/capitalraidseasons", params
    )

players 

players(
    player_tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get player information

Source code in cocapi/api_methods.py 
119
120
121
122
123
124
125
126
127
128
129
def players(
    self, player_tag: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get player information"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM

    player_tag = clean_tag(player_tag)
    return self._api_response(
        f"/players/%23{urllib.parse.quote(player_tag)}", params
    )

clan 

clan(
    name: str = "",
    limit: int = 10,
    params: dict[str, Any] | None = None,
    war_frequency: str | None = None,
    location_id: int | None = None,
    min_members: int | None = None,
    max_members: int | None = None,
    min_clan_points: int | None = None,
    min_clan_level: int | None = None,
    label_ids: str | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Search clans by name and/or filtering criteria

PARAMETER DESCRIPTION
name

Search clans by name (min 3 characters if used)

TYPE: str DEFAULT: ''

limit

Limit number of results

TYPE: int DEFAULT: 10

params

Optional pagination params (after, before)

TYPE: dict[str, Any] | None DEFAULT: None

war_frequency

Filter by war frequency

TYPE: str | None DEFAULT: None

location_id

Filter by location identifier

TYPE: int | None DEFAULT: None

min_members

Filter by minimum number of members

TYPE: int | None DEFAULT: None

max_members

Filter by maximum number of members

TYPE: int | None DEFAULT: None

min_clan_points

Filter by minimum clan points

TYPE: int | None DEFAULT: None

min_clan_level

Filter by minimum clan level

TYPE: int | None DEFAULT: None

label_ids

Comma separated list of label IDs to filter by

TYPE: str | None DEFAULT: None

Source code in cocapi/api_methods.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def clan(
    self,
    name: str = "",
    limit: int = 10,
    params: dict[str, Any] | None = None,
    war_frequency: str | None = None,
    location_id: int | None = None,
    min_members: int | None = None,
    max_members: int | None = None,
    min_clan_points: int | None = None,
    min_clan_level: int | None = None,
    label_ids: str | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Search clans by name and/or filtering criteria

    Args:
        name: Search clans by name (min 3 characters if used)
        limit: Limit number of results
        params: Optional pagination params (after, before)
        war_frequency: Filter by war frequency
        location_id: Filter by location identifier
        min_members: Filter by minimum number of members
        max_members: Filter by maximum number of members
        min_clan_points: Filter by minimum clan points
        min_clan_level: Filter by minimum clan level
        label_ids: Comma separated list of label IDs to filter by
    """
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM

    search_params: dict[str, Any] = {"name": name, "limit": limit}

    if war_frequency is not None:
        search_params["warFrequency"] = war_frequency
    if location_id is not None:
        search_params["locationId"] = location_id
    if min_members is not None:
        search_params["minMembers"] = min_members
    if max_members is not None:
        search_params["maxMembers"] = max_members
    if min_clan_points is not None:
        search_params["minClanPoints"] = min_clan_points
    if min_clan_level is not None:
        search_params["minClanLevel"] = min_clan_level
    if label_ids is not None:
        search_params["labelIds"] = label_ids

    if params:
        search_params.update(params)

    return self._api_response("/clans", search_params)

warleague 

warleague(
    war_tag: str,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get information about a clan war league war

Source code in cocapi/api_methods.py 
183
184
185
186
187
188
def warleague(self, war_tag: str) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get information about a clan war league war"""
    war_tag = clean_tag(war_tag)
    return self._api_response(
        f"/clanwarleagues/wars/%23{urllib.parse.quote(war_tag)}"
    )

location 

location(
    params: dict[str, Any] | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get list of locations

Source code in cocapi/api_methods.py 
190
191
192
193
194
195
196
def location(
    self, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get list of locations"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response("/locations", params)

location_id 

location_id(
    location_id: str,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get information about a location

Source code in cocapi/api_methods.py 
198
199
200
201
202
def location_id(
    self, location_id: str
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get information about a location"""
    return self._api_response(f"/locations/{str(location_id)}")

location_id_clan_rank 

location_id_clan_rank(
    location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get clan rankings for a location

Source code in cocapi/api_methods.py 
204
205
206
207
208
209
210
211
212
def location_id_clan_rank(
    self, location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get clan rankings for a location"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response(
        f"/locations/{str(location_id)}/rankings/clans", params
    )

location_id_player_rank 

location_id_player_rank(
    location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get player rankings for a location

Source code in cocapi/api_methods.py 
214
215
216
217
218
219
220
221
222
def location_id_player_rank(
    self, location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get player rankings for a location"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response(
        f"/locations/{str(location_id)}/rankings/players", params
    )

location_clan_versus 

location_clan_versus(
    location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get clan versus rankings for a location (possibly deprecated)

Source code in cocapi/api_methods.py 
224
225
226
227
228
229
230
231
232
233
234
def location_clan_versus(
    self, location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get clan versus rankings for a location (possibly deprecated)"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._deprecated_api_response(
        f"/locations/{str(location_id)}/rankings/clans-versus",
        "location_clan_versus",
        params,
    )

location_player_versus 

location_player_versus(
    location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get player versus rankings for a location (possibly deprecated)

Source code in cocapi/api_methods.py 
236
237
238
239
240
241
242
243
244
245
246
def location_player_versus(
    self, location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get player versus rankings for a location (possibly deprecated)"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._deprecated_api_response(
        f"/locations/{str(location_id)}/rankings/players-versus",
        "location_player_versus",
        params,
    )

location_clans_builder_base 

location_clans_builder_base(
    location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get clan builder base rankings for a location

Source code in cocapi/api_methods.py 
248
249
250
251
252
253
254
255
256
def location_clans_builder_base(
    self, location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get clan builder base rankings for a location"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response(
        f"/locations/{str(location_id)}/rankings/clans-builder-base", params
    )

location_players_builder_base 

location_players_builder_base(
    location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get player builder base rankings for a location

Source code in cocapi/api_methods.py 
258
259
260
261
262
263
264
265
266
def location_players_builder_base(
    self, location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get player builder base rankings for a location"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response(
        f"/locations/{str(location_id)}/rankings/players-builder-base", params
    )

league 

league(
    params: dict[str, Any] | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get list of leagues

Source code in cocapi/api_methods.py 
268
269
270
271
272
273
274
def league(
    self, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get list of leagues"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response("/leagues", params)

league_id 

league_id(
    league_id: str,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get league information

Source code in cocapi/api_methods.py 
276
277
278
def league_id(self, league_id: str) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get league information"""
    return self._api_response(f"/leagues/{str(league_id)}")

league_season 

league_season(
    id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get league seasons (Legend League only)

Source code in cocapi/api_methods.py 
280
281
282
283
284
285
286
def league_season(
    self, id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get league seasons (Legend League only)"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response(f"/leagues/{str(id)}/seasons", params)

league_season_id 

league_season_id(
    id: str, sid: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get league season rankings (Legend League only)

Source code in cocapi/api_methods.py 
288
289
290
291
292
293
294
def league_season_id(
    self, id: str, sid: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get league season rankings (Legend League only)"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response(f"/leagues/{str(id)}/seasons/{str(sid)}", params)

warleagues 

warleagues() -> dict[str, Any] | Awaitable[dict[str, Any]]

Get list of clan war leagues

Source code in cocapi/api_methods.py 
296
297
298
def warleagues(self) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get list of clan war leagues"""
    return self._api_response("/warleagues")

warleagues_id 

warleagues_id(
    league_id: str,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get information about a clan war league

Source code in cocapi/api_methods.py 
300
301
302
303
304
def warleagues_id(
    self, league_id: str
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get information about a clan war league"""
    return self._api_response(f"/warleagues/{str(league_id)}")

labels_clans 

labels_clans(
    params: dict[str, Any] | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get labels for clans

Source code in cocapi/api_methods.py 
306
307
308
309
310
311
312
def labels_clans(
    self, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get labels for clans"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response("/labels/clans", params)

labels_players 

labels_players(
    params: dict[str, Any] | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get labels for players

Source code in cocapi/api_methods.py 
314
315
316
317
318
319
320
def labels_players(
    self, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get labels for players"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response("/labels/players", params)

capitalleagues 

capitalleagues(
    params: dict[str, Any] | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get list of capital leagues

Source code in cocapi/api_methods.py 
322
323
324
325
326
327
328
def capitalleagues(
    self, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get list of capital leagues"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response("/capitalleagues", params)

capitalleagues_id 

capitalleagues_id(
    league_id: str,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get information about a capital league

Source code in cocapi/api_methods.py 
330
331
332
333
334
def capitalleagues_id(
    self, league_id: str
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get information about a capital league"""
    return self._api_response(f"/capitalleagues/{str(league_id)}")

builderbaseleagues 

builderbaseleagues(
    params: dict[str, Any] | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get list of builder base leagues

Source code in cocapi/api_methods.py 
336
337
338
339
340
341
342
def builderbaseleagues(
    self, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get list of builder base leagues"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response("/builderbaseleagues", params)

builderbaseleagues_id 

builderbaseleagues_id(
    league_id: str,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get information about a builder base league

Source code in cocapi/api_methods.py 
344
345
346
347
348
def builderbaseleagues_id(
    self, league_id: str
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get information about a builder base league"""
    return self._api_response(f"/builderbaseleagues/{str(league_id)}")

goldpass 

goldpass(
    params: dict[str, Any] | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get information about the current gold pass season

Source code in cocapi/api_methods.py 
350
351
352
353
354
355
356
def goldpass(
    self, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get information about the current gold pass season"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response("/goldpass/seasons/current", params)

verify_player_token 

verify_player_token(
    player_tag: str, token: str
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Verify a player API token to confirm account ownership

PARAMETER DESCRIPTION
player_tag

Tag of the player

TYPE: str

token

API token found in the player's game settings

TYPE: str

Source code in cocapi/api_methods.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
def verify_player_token(
    self, player_tag: str, token: str
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Verify a player API token to confirm account ownership

    Args:
        player_tag: Tag of the player
        token: API token found in the player's game settings
    """
    player_tag = clean_tag(player_tag)
    return self._api_post_response(
        f"/players/%23{urllib.parse.quote(player_tag)}/verifytoken",
        {"token": token},
    )

leaguetiers 

leaguetiers(
    params: dict[str, Any] | None = None,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get list of league tiers

Source code in cocapi/api_methods.py 
375
376
377
378
379
380
381
def leaguetiers(
    self, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get list of league tiers"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response("/leaguetiers", params)

leaguetiers_id 

leaguetiers_id(
    league_tier_id: str,
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get information about a specific league tier

Source code in cocapi/api_methods.py 
383
384
385
386
387
def leaguetiers_id(
    self, league_tier_id: str
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get information about a specific league tier"""
    return self._api_response(f"/leaguetiers/{str(league_tier_id)}")

location_capital_rankings 

location_capital_rankings(
    location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]

Get capital rankings for a location

Source code in cocapi/api_methods.py 
389
390
391
392
393
394
395
396
397
def location_capital_rankings(
    self, location_id: str, params: dict[str, Any] | None = None
) -> dict[str, Any] | Awaitable[dict[str, Any]]:
    """Get capital rankings for a location"""
    if not self._validate_params(params):
        return self.ERROR_INVALID_PARAM
    return self._api_response(
        f"/locations/{str(location_id)}/rankings/capitals", params
    )