WarEraAPI.client module¶

class WarEraAPI.client.WarEraClient(api_key: str | None = None, rate_limit: int = 200, bulk_requests_mode: Literal['sequential', 'parallel'] = 'parallel')¶

Bases: object

async get_all_countries()¶

get all the countries

Returns:: a list of Country objects
Return type:: list[Country]

async get_all_regions()¶

get all regions

Returns:: list of Region objects
Return type:: list[Region]

async get_article()¶

get info about an article

Parameters:: articleId (str) – the article Id
Returns:: an Article object
Return type:: Article

async get_article_lite()¶

get less info about an Article

Parameters:: articleId (str) – the article Id
Returns:: an Article object with all of its optional fields set to None
Return type:: Article

async get_articles()¶

get many articles with optional filtering with article_type,categories an languages

Parameters:

type (ARTICLE_TYPE) – the type of returned articles
limit (int) – the amount of Articles returned
cursor (str | None) – the key for fetching the next page results
userId (str | None) – the user Id
categories (list[ARTICLE_CATEGORY] | None) – a list of ARTICLE_CATEGORY to filter with
languages (list[str] | None) – a list of languages to filter with
positiveScoreOnly (bool) – wether to return only positive articles or not (positive = article with > 0 (likes-dislikes))

Returns:

a tuple with the first index holding a list of Article objects and the second holding the next cursor (optional)

Return type:

tuple[list[Article], str | None]

async get_avg_equipment_price()¶

Parameters:: item (ITEM_MARKET_CODE) – the equipment code
Returns:: the price
Return type:: float

async get_battle()¶

get info about a battle

Parameters:: battleId (str) – the battle Id
Returns:: a Battle object
Return type:: Battle

async get_battle_orders()¶

get the orders for a specific battle

Parameters:

battleId (str) – the battle Id
side (Literal["attacker", "defender"]) – the orders for the attacker or the defender side

Returns:

a list of BattleOrder objects

Return type:

list[BattleOrder]

async get_battles()¶

get many battles with optional filtering with war or country Id

Parameters:

isActive (bool) – wether to return only active battles or not
limit (int) – the amount of battles returned
cursor (str | None) – the key for fetching the next page results
direction (Literal["forward", "backward"]) – the direction
filter (BATTLE_FILTER) – filter which battle
defenderRegionId (str | None) – the id of the defender Region (optional)
warId (str | None) – the war Id (optional)
countryId (str | None) – the country Id (optional)

Returns:

a tuple with the first index holding list of Battle objects and the second holding an optional cursor

Return type:

tuple[list[Battle], str | None]

async get_companies(userId: str | None = None, cursor: str | None = None, limit: int = 10, return_companies: bool = False) → tuple[list[str] | list[Company], str | None]¶

company.getCompanies endpoint

Parameters:

userId (str | None) – filter companies by user
cursor (str | None) – used for pagination
limit (int) – number of results per query
return_companies (bool) – whether to return the Companies as list[Company] instead of list[str] (the ids)

Returns:

tuple[0] = list[str] or list[Company], tuple[1] = next_cursor (use it for next page in the “cursor” argument)

Return type:

tuple[list[str] | list[Company], str | None]

async get_company(companyId: str = 'String') → Company¶

company.get_company endpoint

Parameters:: companyId (str) – the company Id
Returns:: returns Company object on success
Return type:: Company

async get_company_production_bonus()¶

Parameters:: companyId (str) – the company Id
Returns:: returns ProductionBonus object for that company
Return type:: ProductionBonus

async get_company_recommended_regions(item_code: Literal['limestone', 'iron', 'petroleum', 'concrete', 'steel', 'oil', 'grain', 'livestock', 'fish', 'bread', 'steak', 'cookedFish', 'lead', 'ammo', 'lightAmmo', 'heavyAmmo', 'case1', 'case2', 'scraps', 'cocain', 'coca'], include_deposits: bool = True) → list[RecommendedRegion]¶

company.get_recommended_region_ids_by_item_code

Parameters:

item_code (ITEM) – the item Code to fetch its regions
include_deposits (bool) – whether to include regions with active deposits or not (defaults to True)

Return type:

list[RecommendedRegion]

async get_company_work_offer()¶

get work offer for a certain company

Parameters:: companyId (str) – the company Id
Returns:: a WorkOffer object
Return type:: WorkOffer

async get_country()¶

get info about a country

Parameters:: countryId (str) – the country Id
Returns:: a Country object
Return type:: Country

async get_country_users()¶

get users from a certain country

Parameters:

countryId (str) – the country Id
limit (int) – the amount of users returned with each page
cursor (str | None) – the key for fetching the next page results
return_users (bool) – wether to return User objects or just user Ids

Returns:

a tuple with the first index holding a list of User objects (or dict[str, str] in case of return_users=False) and the second index holding the next cursor (optional)

Return type:

tuple[list[User] | dict[str, str], str | None]

async get_entity_upgrade()¶

get the current upgrades this entity have entity is a region,mu or company

Parameters:

upgradeType (UPGRADE_TYPE) – the upgrade type to fetch
regionId (str | None) – the region Id
muId (str | None) – the military unit Id
companyId (str | None) – the company Id

Returns:

a EntityUpgrade object

Return type:

EntityUpgrade

async get_events()¶

get a list of events and optionally filter with Country Id

Parameters:

limit (int) – the amount of events returned
cursor (str | None) – the key for fetching the next page results
countryId (str | None) – an optional Country Id to filter ITs events
eventTypes (list[EVENT_TYPES] | None) – specific event type to fetch (optional)

Returns:

a tuple with the first index holding list of Event objects and the second optionally holding the next cursor

Return type:

tuple[list[Event], str | None]

async get_game_dates()¶

Parameters:: self – Description
Returns:: Description
Return type:: GameDates

async get_government()¶

get info about a country’s government

Parameters:: countryId (str) – the country Id
Returns:: a Government object
Return type:: Government

async get_live_battle_data()¶

get live data from a battle

Parameters:

battleId (str) – the battle Id
roundNumber (int) – the round number

Returns:

BattleData object

Return type:

BattleData

async get_many_mu()¶

get many MilitaryUnits with optional filtering with member,user Id or search

Parameters:

limit (int) – the amount of returned MilitaryUnit objects
cursor (str | None) – the key for fetching the next page results
memberId (str | None) – an optional member Id
userId (str | None) – an optional user Id
search (str | None) – optional text to filter with

Returns:

a tuple with first index holding the list of MilitaryUnit objects and the second holding the next cursor (optional)

Return type:

tuple[list[MilitaryUnit], str | None]

async get_mu()¶

get info about a military unit

Parameters:: muId (str) – the military unit Id
Returns:: a MilitaryUnit object
Return type:: MilitaryUnit

async get_party()¶

Parameters:: partyId (str) – the party Id
Returns:: a Party object
Return type:: Party

async get_prices()¶

get current items market price

Returns:: MAPPING[ItemCode: priceInCoins]
Return type:: dict[ITEM, float]

async get_rankings()¶

get the current rankings of RANKING_TYPE

Parameters:: type (RANKING_TYPE) – the ranking type
Returns:: Rankings object
Return type:: Rankings

async get_region()¶

get region info

Parameters:: regionId (str) – the region Id
Returns:: a Region object
Return type:: Region

async get_round()¶

get a battle Round info

Parameters:: roundId (str) – the round Id
Returns:: Round object
Return type:: Round

async get_round_last_hits()¶

get last hits from a round

Parameters:: roundId (str) – the round Id
Returns:: a tuple with the first index holding a list of BattleHit for the attacker side and the second index holding a list of BattleHit for the defender side
Return type:: tuple[list[BattleHit], list[BattleHit]]

async get_top_orders()¶

gets the top orders for an item

Parameters:

itemCode (ITEM) – the item Code
limit (int) – amount of orders returned

Returns:

a tuple with the first index holding the buyOrders and the second holding the sellOrders

Return type:

tuple[list[TradingOrder], list[TradingOrder]]

async get_total_workers_count()¶

get the total number of workers working for a specific user

Parameters:: userId (str) – the user Id
Returns:: the amount of workers
Return type:: int

async get_transactions()¶

get many transactions with optional filtering with user,mu,country,party Id or itemCode depending on transactionType

Parameters:

transactionType (TRANSACTION_TYPE) – the transaction type to filter
limit (int) – the amount of transactions returned
cursor (str | None) – the key for fetching the next page results
userId (str | None) – optional userId to filter with
muId (str | None) – optional military unit Id to filter with
countryId (str | None) – optional country Id to filter with
partyId (str | None) – optional party Id to filter with
itemCode (ITEM | ITEM_MARKET_CODE | None) – the item code to filter with (ITEM for supplies and ITEM_MARKET_CODE for equipments)

Returns:

a tuple with its first index holding the list of Transaction Objects and the second optionally holding the next Cursor

Return type:

tuple[list[Transaction], str | None]

async get_user()¶

get info about a user

Parameters:: userId (str) – the user Id
Returns:: a User object
Return type:: User

async get_user_inventory()¶

get a user equipments

Parameters:: userId (str) – the user Id

async get_user_lite()¶

get less info about user

Parameters:: userId (str) – the user Id
Returns:: a User object with all of its optional fields set to None
Return type:: User

async get_work_offer()¶

get info about a work offer

Parameters:: workOfferId (str) – the work offer Id
Returns:: WorkOffer object
Return type:: WorkOffer

async get_work_offers()¶

get many work offers and optionally filter them by region, user or citizenship

Parameters:

regionId (str | None) – the region Id
userId (str | None) – the user Id
cursor (str | None) – the key for fetching the next page results
limit (int) – the amount of WorkOffer’s returned
energy (int) – the min energy requirement
production (int) – the min production requirement
citizenship (str | None) – the country name

Returns:

tuple with the first index holding the WorkOffer objects and the second having the next cursor (optional)

Return type:

tuple[list[WorkOffer], str | None]

async get_workers()¶

get a list of workers for a company

Parameters:

companyId (str) – the company Id
userId (str | None) – the employer Id to filter with

Returns:

a list of Worker objects

Return type:

list[Worker]

async request(method: Literal['GET', 'POST'], endpoint: str, headers: dict | None = None, body: dict | None = None) → Any¶

sanitize_body(body: dict) → None¶

sanitize_response()¶

Parameters:: data (dict | list[dict]) – the raw api response

async search(searchText: str) → SearchResult¶

search.searchAnything search for any user,region,country,party or Mu by text search

Parameters:: searchText (str) – the text to search with
Returns:: SearchResult object
Return type:: SearchResult