Client

Client construction, authentication, request behavior, and high-level Clash API methods.

Client

struct clashy.Client

Client is the high-level Clash API client.

A Client owns its configuration, HTTP transport, and embedded static-data indexes. It is safe to reuse a single client across request handlers as long as callers pass appropriate contexts.

Client Config

struct clashy.ClientConfig

ClientConfig controls API endpoints, authentication behavior, request throttling, response caching, and static-data loading.

Most callers should start from DefaultClientConfig and override only the fields that differ for their service. The zero value is not the recommended production configuration because it has no API base URL or timeout.

KeyCount

int

KeyCount is the number of developer-site API keys Login should make available for token rotation.

KeyNames

string

KeyNames is the developer-site key name used when reusing or creating API keys during Login.

ThrottleLimit

int

ThrottleLimit is the maximum number of concurrent HTTP requests allowed by the client. A value less than or equal to zero disables the limiter.

Timeout

time.Duration

Timeout is applied to the underlying http.Client.

BaseURL

string

BaseURL is the Clash API or compatible proxy base URL, usually ending in /v1 without a trailing slash.

DeveloperBaseURL

string

DeveloperBaseURL is the developer-site base URL used only by Login.

IP

string

IP overrides the IP address used when Login creates developer-site API keys. When empty, the IP is inferred from the temporary developer token.

Realtime

bool

Realtime adds realtime=true to current-war requests that support it.

CorrectTags

bool

CorrectTags enables Clash tag normalization before tags are placed in API paths or query strings.

CacheMaxSize

int

CacheMaxSize bounds the number of GET responses retained in memory.

LookupCache

bool

LookupCache allows GET requests to return fresh cached responses.

UpdateCache

bool

UpdateCache allows successful GET responses to refresh the in-memory cache.

IgnoreCachedErrors

[]int

IgnoreCachedErrors is reserved for compatibility with callers that model cache behavior after coc.py; current request handling does not use it.

RawJSON

bool

RawJSON is reserved for callers that need raw response capture; current high-level methods unmarshal into typed models.

LoadGameData

LoadGameData

LoadGameData describes when static game data should be loaded.

UserAgent

string

UserAgent is sent with Clash API or proxy requests.

DeveloperUserAgent

string

DeveloperUserAgent is sent with developer-site login and key-management requests.

Search Clans Request

struct clashy.SearchClansRequest

SearchClansRequest contains optional filters for SearchClans.

Zero values are omitted from the query string, matching Clash API search behavior.

Name

string

Name filters clans by name.

WarFrequency

string

WarFrequency filters clans by declared war frequency.

LocationID

int

LocationID filters clans by location ID.

MinMembers

int

MinMembers filters out clans with fewer members.

MaxMembers

int

MaxMembers filters out clans with more members.

MinClanPoints

int

MinClanPoints filters by minimum clan points.

MinClanLevel

int

MinClanLevel filters by minimum clan level.

LabelIDs

[]int

LabelIDs filters by one or more clan label IDs.

Limit

int

Limit controls the number of results requested.

Before

string

Before is a pagination cursor.

After

string

After is a pagination cursor.

Request Options

struct clashy.RequestOptions

RequestOptions controls per-request behavior for HTTPClient.Do.

LookupCache

bool

LookupCache allows a GET request to return a fresh cached response.

UpdateCache

bool

UpdateCache allows a successful GET request to store or replace a cached response.

SkipAuth

bool

SkipAuth prevents Do from adding an Authorization header.

HTTPClient

struct clashy.HTTPClient

HTTPClient performs low-level Clash API and developer-site HTTP requests.

Most callers should use Client instead. HTTPClient is exported so advanced integrations can build compatible request flows while reusing token rotation, throttling, compression handling, cache storage, and typed error mapping.

Client Methods

clashy.Client.Close() -> error

Close releases client resources.

The current implementation does not hold resources that need explicit teardown, so Close returns nil.

Return type:
error

clashy.Client.GetBattleLog(ctx: context.Context, playerTag: string) -> ([]BattleLogEntry, error)

GetBattleLog fetches a player's battle log.

Parameters:

ctx (context.Context)

playerTag (string)

Return type:
[]BattleLogEntry error

clashy.Client.GetBuilderBaseLeague(ctx: context.Context, id: int) -> (*League, error)

GetBuilderBaseLeague fetches a Builder Base league by ID.

Parameters:

ctx (context.Context)

id (int)

Return type:
*League error

clashy.Client.GetCapitalLeague(ctx: context.Context, id: int) -> (*League, error)

GetCapitalLeague fetches a Clan Capital league by ID.

Parameters:

ctx (context.Context)

id (int)

Return type:
*League error

clashy.Client.GetClan(ctx: context.Context, tag: string) -> (*Clan, error)

GetClan fetches a clan profile by tag.

Parameters:

ctx (context.Context)

tag (string)

Return type:
*Clan error

clashy.Client.GetClanLabels(ctx: context.Context, limit: int, before: string, after: string) -> ([]Label, error)

GetClanLabels fetches clan labels with optional pagination.

Parameters:

ctx (context.Context)

limit (int)

before (string)

after (string)

Return type:
[]Label error

clashy.Client.GetClanWar(ctx: context.Context, clanTag: string) -> (*ClanWar, error)

GetClanWar fetches the regular current-war endpoint for a clan.

This method does not fall back to CWL. Use GetCurrentWar when you want the active normal war or the relevant Clan War League war.

Parameters:

ctx (context.Context)

clanTag (string)

Return type:
*ClanWar error

clashy.Client.GetClanWars(ctx: context.Context, tags: []string) -> ([]ClanWar, error)

GetClanWars fetches the regular current war for each clan tag in order.

Parameters:

ctx (context.Context)

tags ([]string)

Return type:
[]ClanWar error

clashy.Client.GetCurrentGoldPassSeason(ctx: context.Context) -> (*GoldPassSeason, error)

GetCurrentGoldPassSeason fetches the current Gold Pass season.

Parameters:

ctx (context.Context)

Return type:
*GoldPassSeason error

clashy.Client.GetCurrentWar(ctx: context.Context, clanTag: string, round: ...WarRound) -> (*ClanWar, error)

GetCurrentWar returns the clan's active normal war or relevant CWL war.

The method first checks the regular current-war endpoint. If the clan is not in a regular war, or the war log is private, it loads the CWL group and returns the selected league round for the clan. Passing no round selects CurrentWar. When no current war exists, the method returns nil, nil.

Parameters:

ctx (context.Context)

clanTag (string)

round (...WarRound)

Return type:
*ClanWar error

clashy.Client.GetCurrentWars(ctx: context.Context, tags: []string) -> ([]ClanWar, error)

GetCurrentWars fetches GetCurrentWar for each clan tag and omits clans with no current war.

Parameters:

ctx (context.Context)

tags ([]string)

Return type:
[]ClanWar error

clashy.Client.GetEquipment(name: string, level: int) -> *Equipment

GetEquipment looks up hero equipment by name and level in embedded static data.

Parameters:

name (string)

level (int)

Return type:
*Equipment

clashy.Client.GetExtendedCWLGroupData(name: string) -> *ExtendedCWLGroup

GetExtendedCWLGroupData returns static medal data for a Clan War League tier by name.

Parameters:

name (string)

Return type:
*ExtendedCWLGroup

clashy.Client.GetHero(name: string, level: int) -> *Hero

GetHero looks up a hero by name and level in embedded static data.

Parameters:

name (string)

level (int)

Return type:
*Hero

clashy.Client.GetLeague(ctx: context.Context, id: int) -> (*League, error)

GetLeague fetches a home-village league by ID.

Parameters:

ctx (context.Context)

id (int)

Return type:
*League error

clashy.Client.GetLeagueGroup(ctx: context.Context, clanTag: string) -> (*ClanWarLeagueGroup, error)

GetLeagueGroup fetches the current Clan War League group for a clan.

Parameters:

ctx (context.Context)

clanTag (string)

Return type:
*ClanWarLeagueGroup error

clashy.Client.GetLeagueWar(ctx: context.Context, clanTag: string, round: WarRound) -> (*ClanWar, error)

GetLeagueWar fetches the selected CWL round for a clan.

The returned war is oriented so Clan is the requested clan and Opponent is the opposing side.

Parameters:

ctx (context.Context)

clanTag (string)

round (WarRound)

Return type:
*ClanWar error

clashy.Client.GetLeagueWars(ctx: context.Context, warTags: []string) -> ([]ClanWar, error)

GetLeagueWars fetches CWL wars by war tag.

Parameters:

ctx (context.Context)

warTags ([]string)

Return type:
[]ClanWar error

clashy.Client.GetLocation(ctx: context.Context, locationID: int) -> (*Location, error)

GetLocation fetches a location by numeric ID.

Parameters:

ctx (context.Context)

locationID (int)

Return type:
*Location error

clashy.Client.GetLocationClans(ctx: context.Context, locationID: int, limit: int, before: string, after: string) -> ([]RankedClan, error)

GetLocationClans fetches home-village clan rankings for a numeric location ID.

Parameters:

ctx (context.Context)

locationID (int)

limit (int)

before (string)

after (string)

Return type:
[]RankedClan error

clashy.Client.GetLocationClansBuilderBase(ctx: context.Context, locationID: int, limit: int, before: string, after: string) -> ([]RankedClan, error)

GetLocationClansBuilderBase fetches Builder Base clan rankings for a numeric location ID.

Parameters:

ctx (context.Context)

locationID (int)

limit (int)

before (string)

after (string)

Return type:
[]RankedClan error

clashy.Client.GetLocationClansBuilderBaseByLocationID(ctx: context.Context, locationID: string, limit: int, before: string, after: string) -> ([]RankedClan, error)

GetLocationClansBuilderBaseByLocationID fetches Builder Base clan rankings for a location ID string.

Parameters:

ctx (context.Context)

locationID (string)

limit (int)

before (string)

after (string)

Return type:
[]RankedClan error

clashy.Client.GetLocationClansByLocationID(ctx: context.Context, locationID: string, limit: int, before: string, after: string) -> ([]RankedClan, error)

GetLocationClansByLocationID fetches home-village clan rankings for a location ID string.

Parameters:

ctx (context.Context)

locationID (string)

limit (int)

before (string)

after (string)

Return type:
[]RankedClan error

clashy.Client.GetLocationClansCapital(ctx: context.Context, locationID: int, limit: int, before: string, after: string) -> ([]RankedClan, error)

GetLocationClansCapital fetches Clan Capital clan rankings for a numeric location ID.

Parameters:

ctx (context.Context)

locationID (int)

limit (int)

before (string)

after (string)

Return type:
[]RankedClan error

clashy.Client.GetLocationClansCapitalByLocationID(ctx: context.Context, locationID: string, limit: int, before: string, after: string) -> ([]RankedClan, error)

GetLocationClansCapitalByLocationID fetches Clan Capital clan rankings for a location ID string.

Parameters:

ctx (context.Context)

locationID (string)

limit (int)

before (string)

after (string)

Return type:
[]RankedClan error

clashy.Client.GetLocationNamed(ctx: context.Context, locationName: string) -> (*Location, error)

GetLocationNamed returns the first location whose name matches locationName case-insensitively.

It returns nil, nil when no matching location is found.

Parameters:

ctx (context.Context)

locationName (string)

Return type:
*Location error

clashy.Client.GetLocationPlayers(ctx: context.Context, locationID: int, limit: int, before: string, after: string) -> ([]RankedPlayer, error)

GetLocationPlayers fetches home-village player rankings for a numeric location ID.

Parameters:

ctx (context.Context)

locationID (int)

limit (int)

before (string)

after (string)

Return type:
[]RankedPlayer error

clashy.Client.GetLocationPlayersBuilderBase(ctx: context.Context, locationID: int, limit: int, before: string, after: string) -> ([]RankedPlayer, error)

GetLocationPlayersBuilderBase fetches Builder Base player rankings for a numeric location ID.

Parameters:

ctx (context.Context)

locationID (int)

limit (int)

before (string)

after (string)

Return type:
[]RankedPlayer error

clashy.Client.GetLocationPlayersBuilderBaseByLocationID(ctx: context.Context, locationID: string, limit: int, before: string, after: string) -> ([]RankedPlayer, error)

GetLocationPlayersBuilderBaseByLocationID fetches Builder Base player rankings for a location ID string.

Parameters:

ctx (context.Context)

locationID (string)

limit (int)

before (string)

after (string)

Return type:
[]RankedPlayer error

clashy.Client.GetLocationPlayersByLocationID(ctx: context.Context, locationID: string, limit: int, before: string, after: string) -> ([]RankedPlayer, error)

GetLocationPlayersByLocationID fetches home-village player rankings for a location ID string.

Parameters:

ctx (context.Context)

locationID (string)

limit (int)

before (string)

after (string)

Return type:
[]RankedPlayer error

clashy.Client.GetMembers(ctx: context.Context, clanTag: string, limit: int, after: string, before: string) -> ([]ClanMember, error)

GetMembers fetches a clan member page by clan tag.

Parameters:

ctx (context.Context)

clanTag (string)

limit (int)

after (string)

before (string)

Return type:
[]ClanMember error

clashy.Client.GetPet(name: string, level: int) -> *Pet

GetPet looks up a pet by name and level in embedded static data.

Parameters:

name (string)

level (int)

Return type:
*Pet

clashy.Client.GetPlayer(ctx: context.Context, tag: string) -> (*Player, error)

GetPlayer fetches a player profile by tag.

Parameters:

ctx (context.Context)

tag (string)

Return type:
*Player error

clashy.Client.GetPlayerLabels(ctx: context.Context, limit: int, before: string, after: string) -> ([]Label, error)

GetPlayerLabels fetches player labels with optional pagination.

Parameters:

ctx (context.Context)

limit (int)

before (string)

after (string)

Return type:
[]Label error

clashy.Client.GetPlayerLeagueGroup(ctx: context.Context, playerTag: string, leagueGroupTag: string, leagueSeasonID: int) -> (*LeagueTierGroup, error)

GetPlayerLeagueGroup fetches a legend league group and scopes it to a player.

Parameters:

ctx (context.Context)

playerTag (string)

leagueGroupTag (string)

leagueSeasonID (int)

Return type:
*LeagueTierGroup error

clashy.Client.GetPlayerLeagueHistory(ctx: context.Context, playerTag: string) -> ([]LeagueHistoryEntry, error)

GetPlayerLeagueHistory fetches a player's legend league history.

Parameters:

ctx (context.Context)

playerTag (string)

Return type:
[]LeagueHistoryEntry error

clashy.Client.GetRaidLog(ctx: context.Context, clanTag: string, limit: int, after: string, before: string) -> ([]RaidLogEntry, error)

GetRaidLog fetches Clan Capital raid weekend log entries for a clan.

Parameters:

ctx (context.Context)

clanTag (string)

limit (int)

after (string)

before (string)

Return type:
[]RaidLogEntry error

clashy.Client.GetSeasonRankings(ctx: context.Context, leagueID: int, seasonID: string) -> ([]RankedPlayer, error)

GetSeasonRankings fetches player rankings for a league season.

Parameters:

ctx (context.Context)

leagueID (int)

seasonID (string)

Return type:
[]RankedPlayer error

clashy.Client.GetSeasons(ctx: context.Context, leagueID: int) -> ([]string, error)

GetSeasons fetches available season IDs for a league.

Passing leagueID 0 uses the default legend league ID.

Parameters:

ctx (context.Context)

leagueID (int)

Return type:
[]string error

clashy.Client.GetSpell(name: string, level: int) -> *Spell

GetSpell looks up a spell by name and level in embedded static data.

Parameters:

name (string)

level (int)

Return type:
*Spell

clashy.Client.GetTranslation(id: string) -> *Translation

GetTranslation returns a translation entry by static-data translation ID.

Parameters:

id (string)

Return type:
*Translation

clashy.Client.GetTroop(name: string, isHomeVillage: bool, level: int) -> *Troop

GetTroop looks up a troop by name, village, and level in embedded static data.

Parameters:

name (string)

isHomeVillage (bool)

level (int)

Return type:
*Troop

clashy.Client.GetWarLeague(ctx: context.Context, id: int) -> (*League, error)

GetWarLeague fetches a Clan War League tier by ID.

Parameters:

ctx (context.Context)

id (int)

Return type:
*League error

clashy.Client.GetWarLog(ctx: context.Context, clanTag: string, limit: int, after: string, before: string) -> ([]ClanWarLogEntry, error)

GetWarLog fetches public war log entries for a clan.

Parameters:

ctx (context.Context)

clanTag (string)

limit (int)

after (string)

before (string)

Return type:
[]ClanWarLogEntry error

clashy.Client.Login(ctx: context.Context, email: string, password: string) -> error

Login authenticates with developer-site email and password credentials.

The developer login flow discovers or creates API keys, stores them in the underlying HTTP client, and uses those keys for later Clash API requests.

Parameters:

ctx (context.Context)

email (string)

password (string)

Return type:
error

clashy.Client.LoginWithTokens(_: context.Context, tokens: ...string) -> error

LoginWithTokens configures one or more existing Clash API tokens.

Tokens are rotated by the underlying HTTP client. The context parameter is accepted for API symmetry with Login.

Parameters:

_ (context.Context)

tokens (...string)

Return type:
error

clashy.Client.ParseAccountData(data: map[string]any) -> AccountData

ParseAccountData wraps arbitrary account-link data without mutating it.

Parameters:

data (map[string]any)

Return type:
AccountData

clashy.Client.ParseArmyLink(link: string) -> ArmyRecipe

ParseArmyLink parses a full Clash army link or raw army payload using the client's static data.

Parameters:

link (string)

Return type:
ArmyRecipe

clashy.Client.SearchBuilderBaseLeagues(ctx: context.Context, limit: int, before: string, after: string) -> ([]League, error)

SearchBuilderBaseLeagues fetches Builder Base leagues with optional pagination.

Parameters:

ctx (context.Context)

limit (int)

before (string)

after (string)

Return type:
[]League error

clashy.Client.SearchCapitalLeagues(ctx: context.Context, limit: int, before: string, after: string) -> ([]League, error)

SearchCapitalLeagues fetches Clan Capital leagues with optional pagination.

Parameters:

ctx (context.Context)

limit (int)

before (string)

after (string)

Return type:
[]League error

clashy.Client.SearchClans(ctx: context.Context, req: SearchClansRequest) -> ([]Clan, error)

SearchClans searches clans using the provided optional filters.

Parameters:

ctx (context.Context)

req (SearchClansRequest)

Return type:
[]Clan error

clashy.Client.SearchLeagues(ctx: context.Context, limit: int, before: string, after: string) -> ([]League, error)

SearchLeagues fetches home-village leagues with optional pagination.

Parameters:

ctx (context.Context)

limit (int)

before (string)

after (string)

Return type:
[]League error

clashy.Client.SearchLocations(ctx: context.Context, limit: int, before: string, after: string) -> ([]Location, error)

SearchLocations fetches API locations with optional pagination.

Parameters:

ctx (context.Context)

limit (int)

before (string)

after (string)

Return type:
[]Location error

clashy.Client.SearchWarLeagues(ctx: context.Context, limit: int, before: string, after: string) -> ([]League, error)

SearchWarLeagues fetches Clan War League tiers with optional pagination.

Parameters:

ctx (context.Context)

limit (int)

before (string)

after (string)

Return type:
[]League error

clashy.Client.StaticData() -> *StaticData

StaticData returns the client's embedded static-data index.

Return type:
*StaticData

clashy.Client.UpdateStatic(ctx: context.Context) -> error

UpdateStatic downloads the latest ClashKing static-data and translation JSON, writes the embedded source files, and refreshes this client's in-memory StaticData.

Parameters:

ctx (context.Context)

Return type:
error

clashy.Client.VerifyPlayerToken(ctx: context.Context, playerTag: string, token: string) -> (bool, error)

VerifyPlayerToken verifies an in-game player API token.

Parameters:

ctx (context.Context)

playerTag (string)

token (string)

Return type:
bool error

HTTPClient Methods

clashy.HTTPClient.Do(ctx: context.Context, method: string, fullURL: string, body: any, options: RequestOptions) -> ([]byte, int, int, error)

Do sends one HTTP request and returns the response body, status code, retry cache duration in seconds, and error.

Non-2xx API responses are converted into the package's typed HTTP errors. Successful GET responses can be read from or written to the in-memory cache depending on RequestOptions.

Parameters:

ctx (context.Context)

method (string)

fullURL (string)

body (any)

options (RequestOptions)

Return type:
[]byte int int error

clashy.HTTPClient.LoginDeveloper(ctx: context.Context, email: string, password: string) -> error

LoginDeveloper authenticates against the Clash developer site and configures API tokens for subsequent Clash API requests.

The method reuses matching keys for the configured IP and key name when possible, creating more keys until ClientConfig.KeyCount is satisfied.

Parameters:

ctx (context.Context)

email (string)

password (string)

Return type:
error

clashy.HTTPClient.SetTokens(tokens: ...string)

SetTokens replaces the API tokens used for Authorization headers.

Tokens are rotated one per request. Passing no tokens clears authentication.

Parameters:

tokens (...string)

Functions

clashy.NewClient(cfg: ClientConfig) -> (*Client, error)

NewClient constructs a Client from cfg and loads embedded static data.

If cfg.BaseURL is empty, DefaultClientConfig is used. BaseURL and DeveloperBaseURL are normalized by removing trailing slashes.

Parameters:

cfg (ClientConfig)

Return type:
*Client error

clashy.DefaultClientConfig() -> ClientConfig

DefaultClientConfig returns the recommended baseline configuration for the official Clash of Clans API.

The defaults enable tag correction, GET response caching, embedded static data, a 30 second timeout, and a conservative request throttle. Callers using a ClashKing proxy typically override BaseURL and may enable Realtime.

Return type:
ClientConfig

clashy.NewHTTPClient(cfg: ClientConfig) -> *HTTPClient

NewHTTPClient constructs an HTTPClient from cfg.

Parameters:

cfg (ClientConfig)

Return type:
*HTTPClient