Getting Started¶

Installation¶

Basic (sync client only)¶

pip install steam-fetcher

With async support¶

pip install steam-fetcher[async]

All optional dependencies¶

pip install steam-fetcher[all]

This includes: aiolimiter (async rate limiting), polars (Parquet export), sqlalchemy (SQL export), typer (CLI).

Clients overview¶

steam-fetcher provides four clients:

Client	Auth required	Sync/Async
`SteamClient`	No	Sync
`AsyncSteamClient`	No	Async
`SteamAuthClient`	Yes	Sync
`AsyncSteamAuthClient`	Yes	Async

Public clients (SteamClient, AsyncSteamClient) access the Steam Store API — game details, player counts, reviews, search, SteamSpy stats. No API key needed.

Auth clients (SteamAuthClient, AsyncSteamAuthClient) extend the public clients with Steam Web API endpoints — user profiles, game libraries, achievements. Requires a Steam Web API key.

Using the sync client¶

All clients are context managers. Use with to ensure the HTTP session is properly closed:

from steam_fetcher import SteamClient

with SteamClient() as client:
    # Game details
    game = client.get_game(730)
    if game:
        print(f"{game.name} — {game.type}")
        print(f"Free: {game.is_free}")
        print(f"Platforms: win={game.platforms.windows}, mac={game.platforms.mac}")

    # Current player count
    players = client.get_player_count(730)
    if players:
        print(f"Online: {players.player_count}")

    # Review summary
    reviews = client.get_reviews(730)
    if reviews:
        print(f"Reviews: {reviews.score_description} ({reviews.positive}/{reviews.total})")

    # Store search
    results = client.search("portal")
    for entry in results.entries:
        print(f"  {entry.app_id}: {entry.name} — {entry.price}")

    # SteamSpy stats
    spy = client.get_steamspy_details(730)
    if spy:
        print(f"Owners: {spy.owners}, Peak CCU: {spy.peak_ccu}")

All methods return None when the requested resource is not found (except search, which always returns a SearchResult).

Using the async client¶

The async client has the same API, but with async/await:

import asyncio
from steam_fetcher import AsyncSteamClient

async def main():
    async with AsyncSteamClient() as client:
        game = await client.get_game(730)
        players = await client.get_player_count(730)

        # Fetch multiple games concurrently
        import asyncio
        games = await asyncio.gather(
            client.get_game(730),
            client.get_game(570),
            client.get_game(440),
        )
        for g in games:
            if g:
                print(g.name)

asyncio.run(main())

The async client includes built-in rate limiting (default: 200 requests/minute). You can configure it:

async with AsyncSteamClient(
    requests_per_minute=100,
    burst_size=5,
    time_period=60.0,
) as client:
    ...

Getting a Steam Web API key¶

Some endpoints (user profiles, libraries, achievements, friends, bans, etc.) require a Steam Web API key.

Go to steamcommunity.com/dev/apikey
Log in with your Steam account
Enter any domain name (e.g. localhost)
Click Register
Copy your key

Store the key in an environment variable:

export STEAM_API_KEY=your_key_here

The key is free and has no expiration. Rate limits are shared across all Steam Web API endpoints.

Using the auth client¶

For endpoints that require a Steam Web API key:

from steam_fetcher import SteamAuthClient

with SteamAuthClient(api_key="YOUR_STEAM_API_KEY") as client:
    # User profile
    profile = client.get_user_profile("76561198000000000")
    if profile:
        print(f"{profile.username} ({profile.steam_id})")
        print(f"Country: {profile.country_code}")
        print(f"Public: {profile.is_public}")

    # Game library
    library = client.get_user_library("76561198000000000")
    if library:
        print(f"Games owned: {library.game_count}")
        for game in library.games[:5]:
            hours = game.playtime_forever / 60
            print(f"  {game.name}: {hours:.0f}h")

    # Achievements
    achievements = client.get_user_achievements("76561198000000000", 730)
    if achievements:
        unlocked = sum(1 for a in achievements.achievements if a.achieved)
        print(f"Achievements: {unlocked}/{len(achievements.achievements)}")

The API key is stored as pydantic.SecretStr and will not appear in logs or repr().

The async version works the same way:

async with AsyncSteamAuthClient(api_key="YOUR_KEY") as client:
    profile = await client.get_user_profile("76561198000000000")

Configuring retries and timeouts¶

All clients accept retries and timeout parameters:

with SteamClient(retries=5, timeout=30.0) as client:
    game = client.get_game(730)

retries (default: 3) — number of retry attempts with exponential backoff
timeout (default: 10.0) — request timeout in seconds

Exporting data¶

steam-fetcher includes exporters for saving data to files or databases:

from steam_fetcher import SteamClient
from steam_fetcher.exporters import JsonExporter, CsvExporter

with SteamClient() as client:
    game = client.get_game(730)

# JSON
JsonExporter().export([game], "games.json")

# CSV (nested fields are flattened)
CsvExporter().export([game], "games.csv")

For Parquet and SQL, install the corresponding extras:

from steam_fetcher.exporters import ParquetExporter, SqlExporter

# Parquet (requires: pip install steam-fetcher[parquet])
ParquetExporter(compression="zstd").export([game], "games.parquet")

# SQL (requires: pip install steam-fetcher[sql])
SqlExporter(url="sqlite:///steam.db").export([game], "games")

See Exporters for full reference.

CLI¶

Install the CLI extra:

pip install steam-fetcher[cli]

Usage:

# Game details → JSON
steam-fetcher games details 730

# Search
steam-fetcher games search "half-life" --format csv --output results.csv

# Player count
steam-fetcher games players 730

# Reviews
steam-fetcher games reviews 730 --format json --output reviews.json

# User profile (requires API key)
steam-fetcher users profile 76561198000000000 --api-key YOUR_KEY

# User library
steam-fetcher users library 76561198000000000 --api-key YOUR_KEY

# Achievements
steam-fetcher users achievements 76561198000000000 730 --api-key YOUR_KEY

The API key can also be set via the STEAM_API_KEY environment variable:

export STEAM_API_KEY=your_key_here
steam-fetcher users profile 76561198000000000

Output formats¶

All commands that export data support --format (json, csv, parquet, sql) and --output flags:

steam-fetcher games details 730 --format csv --output game.csv
steam-fetcher games details 730 --format sql --output games_table --url sqlite:///steam.db