Getting Started

Getting Started

Ready to build your first script with the WarEra Python Client? This guide will walk you through the absolute basics.

1. Installation

Install the library using pip:

pip install warera-client

2. Setting Your API Key

While you can use the library anonymously, you will be heavily rate-limited. It is highly recommended to get an API key from the WarEra settings page.

You can set your API key by passing it to set_api_key():

import warera

warera.set_api_key("YOUR_API_KEY_HERE")

Alternatively, you can just set the WARERA_API_KEY environment variable in your terminal, and the library will detect it automatically!

3. Your First Async Script

Let's write a simple script to fetch a specific country's data and print its name and treasury balance.

import asyncio
import warera

async def main():
    # Fetch country ID '7'
    country = await warera.country.get_by_id("7")
    
    print(f"Welcome to {country.name}!")
    
    # We can access nested fields safely!
    if country.taxes:
        print(f"Income Tax: {country.taxes.income}%")

if __name__ == "__main__":
    asyncio.run(main())

4. Fetching Multiple Items (Auto-Batching)

One of the best features of this library is how it handles multiple requests.

If you want to fetch 5 different users, you don't need to manually combine them into a single payload. Just use .get_many():

import asyncio
import warera

async def main():
    # Pass a list of IDs to get_many()
    user_ids = ["1", "2", "3", "4", "5"]
    
    # The library will automatically bundle these into a SINGLE network request!
    users = await warera.user.get_many(user_ids)
    
    for user in users:
        print(f"{user.name} is level {user.leveling.level}")

if __name__ == "__main__":
    asyncio.run(main())

5. Paginated Endpoints

Many endpoints in WarEra return cursor-paginated data (like lists of articles, battle logs, or users).

The library handles pagination tokens for you automatically via the auto_items=True parameter. This turns the response into an asynchronous generator that you can easily loop over!

import asyncio
import warera

async def main():
    print("Fetching all users in country 7...")
    
    # auto_items=True abstracts away the pagination logic!
    async for user in await warera.user.get_by_country("7", auto_items=True):
        print(user.name)

if __name__ == "__main__":
    asyncio.run(main())

6. Going Huge: The collect_all() Engine

If you need to fetch millions of records (like transaction logs or battle rankings), simple pagination is too slow.

The collect_all() engine solves this by dividing the timeline into chunks and fetching them all concurrently:

import asyncio
import warera

async def main():
    print("Downloading massive transaction history concurrently...")
    
    # This will fire 500 concurrent network requests!
    transactions = await warera.transaction.collect_all(
        oldest_date="2026-01-01T00:00:00Z",
        concurrency=500
    )
    
    print(f"Downloaded {len(transactions)} transactions instantly.")

if __name__ == "__main__":
    asyncio.run(main())

Next Steps

Now that you know the basics, check out the Code Snippets page for quick copy-paste examples of common tasks, or explore the API Reference to see all the endpoints available!