Models¶

All models are Pydantic v2 BaseModel subclasses. Import from steam_fetcher or steam_fetcher.models.

from steam_fetcher import GameDetails, UserProfile, PlayerCount
# or
from steam_fetcher.models import GameDetails, UserProfile, PlayerCount

Game models¶

GameDetails¶

Full game details from the Steam Store API. Returned by get_game().

Field	Type	Description
`app_id`	`int`	Steam application ID
`name`	`str`	Game name
`type`	`AppType`	Application type (`game`, `dlc`, `demo`, etc.)
`is_free`	`bool`	Whether the game is free to play
`short_description`	`str \\| None`	Short description
`about_the_game`	`str \\| None`	About section (HTML)
`detailed_description`	`str \\| None`	Full description (HTML)
`supported_languages`	`list[str]`	Supported languages
`header_image`	`HttpUrl \\| None`	Header image URL
`website`	`HttpUrl \\| None`	Official website URL
`developers`	`list[str]`	Developer names
`publishers`	`list[str]`	Publisher names
`price`	`Price \\| None`	Price info (`None` if free)
`platforms`	`Platforms \\| None`	Supported platforms
`metacritic`	`Metacritic \\| None`	Metacritic score
`categories`	`list[Category]`	Steam categories
`genres`	`list[Genre]`	Game genres
`screenshots`	`list[Screenshot]`	Screenshot URLs
`movies`	`list[Movie]`	Trailer URLs
`release_date`	`ReleaseDate \\| None`	Release date info
`dlc_count`	`int`	Number of DLCs
`achievements`	`int`	Total achievements count
`recommendations`	`int`	Total recommendations
`required_age`	`int`	Minimum required age

AppType¶

StrEnum of Steam application types:

from steam_fetcher import AppType

AppType.GAME        # "game"
AppType.DLC         # "dlc"
AppType.DEMO        # "demo"
AppType.MOD         # "mod"
AppType.VIDEO       # "video"
AppType.SERIES      # "series"
AppType.EPISODE     # "episode"
AppType.BUNDLE      # "bundle"
AppType.ADVERTISING # "advertising"

Price¶

Field	Type	Description
`currency`	`str`	Currency code (e.g. `"USD"`)
`initial`	`float`	Initial price in cents
`final`	`float`	Final price after discount (cents)
`discount_percent`	`int`	Discount percentage (0–100)
`initial_formatted`	`str`	Formatted initial price
`final_formatted`	`str`	Formatted final price

Platforms¶

Field	Type	Default	Description
`windows`	`bool`	`False`	Windows support
`mac`	`bool`	`False`	macOS support
`linux`	`bool`	`False`	Linux support

Metacritic¶

Field	Type	Description
`score`	`int`	Metacritic score (0–100)
`url`	`HttpUrl`	Metacritic review URL

Category / Genre¶

Field	Type	Description
`id`	`int`	Category/genre ID
`description`	`str`	Category/genre name

Screenshot¶

Field	Type	Description
`id`	`int`	Screenshot ID
`path_thumbnail`	`HttpUrl`	Thumbnail URL
`path_full`	`HttpUrl`	Full resolution URL

Movie¶

Field	Type	Description
`id`	`int`	Movie ID
`name`	`str`	Trailer name
`thumbnail`	`HttpUrl`	Thumbnail URL
`webm_max`	`HttpUrl \\| None`	Max quality WebM URL
`mp4_max`	`HttpUrl \\| None`	Max quality MP4 URL

ReleaseDate¶

Field	Type	Description
`coming_soon`	`bool`	Whether the game is unreleased
`date`	`str \\| None`	Release date string (e.g. `"Sep 27, 2023"`)

AppListEntry¶

Entry in the Steam app list. Returned inside AppList.

Field	Type	Description
`appid`	`int`	Steam application ID
`name`	`str`	Application name
`last_modified`	`int`	Last modified timestamp
`price_change_number`	`int`	Price change revision number

AppList¶

Returned by get_app_list().

Field	Type	Description
`apps`	`list[AppListEntry]`	List of applications
`have_more_results`	`bool`	Whether more results are available
`last_appid`	`int`	Last app ID in the list (use as cursor for pagination)

Player models¶

PlayerCount¶

Returned by get_player_count().

Field	Type	Description
`app_id`	`int`	Steam application ID
`player_count`	`int`	Current number of online players

ReviewSummary¶

Returned by get_reviews().

Field	Type	Description
`app_id`	`int`	Steam application ID
`total`	`int`	Total reviews
`positive`	`int`	Positive reviews
`negative`	`int`	Negative reviews
`score`	`int`	Review score (0–10)
`score_description`	`str`	e.g. `"Very Positive"`
`review_type`	`str`	Review type filter
`purchase_type`	`str`	Purchase type filter
`cursor`	`str \\| None`	Cursor for pagination
`reviews`	`list[Review]`	Individual review entries

Review¶

An individual user review. Returned inside ReviewSummary.

Field	Type	Description
`recommendation_id`	`str`	Unique recommendation ID
`author_steam_id`	`str`	Author's Steam 64-bit ID
`language`	`str`	Review language code
`review`	`str`	Review text content
`timestamp_created`	`int`	Creation timestamp (Unix)
`voted_up`	`bool`	Whether the review is positive
`votes_up`	`int`	Helpful votes count
`votes_funny`	`int`	Funny votes count
`weighted_vote_score`	`float`	Weighted helpfulness score
`comment_count`	`int`	Number of comments
`steam_purchase`	`bool`	Whether purchased on Steam
`received_for_free`	`bool`	Whether received for free

SteamSpyDetails¶

Returned by get_steamspy_details().

Field	Type	Description
`app_id`	`int`	Steam application ID
`name`	`str`	Game name
`developer`	`str`	Developer name
`publisher`	`str`	Publisher name
`score_rank`	`str`	Score rank
`positive`	`int`	Positive reviews
`negative`	`int`	Negative reviews
`userscore`	`int`	User score
`owners`	`str`	Estimated owners range (e.g. `"50,000,000 .. 100,000,000"`)
`average_forever`	`int`	Average playtime forever (minutes)
`average_2weeks`	`int`	Average playtime last 2 weeks (minutes)
`median_forever`	`int`	Median playtime forever (minutes)
`median_2weeks`	`int`	Median playtime last 2 weeks (minutes)
`peak_ccu`	`int`	Peak concurrent users
`price`	`str`	Price in cents
`discount`	`int`	Discount percentage (0–100)
`tags`	`dict[str, int]`	Tags with vote counts

GlobalAchievement¶

A single global achievement percentage entry. Returned inside GlobalAchievements.

Field	Type	Description
`name`	`str`	Achievement API name
`percent`	`float`	Global unlock percentage (0–100)

GlobalAchievements¶

Returned by get_global_achievement_percentages().

Field	Type	Description
`app_id`	`int`	Steam application ID
`achievements`	`list[GlobalAchievement]`	Achievement percentages

AchievementSchema¶

Achievement definition from the game schema. Returned inside GameSchema.

Field	Type	Description
`name`	`str`	Achievement API name
`display_name`	`str`	Human-readable name
`description`	`str`	Achievement description
`icon`	`str`	Unlocked icon URL
`icon_gray`	`str`	Locked icon URL

StatSchema¶

Stat definition from the game schema. Returned inside GameSchema.

Field	Type	Description
`name`	`str`	Stat API name
`display_name`	`str`	Human-readable name

GameSchema¶

Returned by get_game_schema().

Field	Type	Description
`app_id`	`int`	Steam application ID
`game_name`	`str`	Game name
`achievements`	`list[AchievementSchema]`	Achievement definitions
`stats`	`list[StatSchema]`	Stat definitions

StatEntry¶

A single stat value for a user. Returned inside UserStats.

Field	Type	Description
`name`	`str`	Stat API name
`value`	`float`	Stat value

UserStats¶

Returned by get_user_stats().

Field	Type	Description
`steam_id`	`str`	Steam 64-bit user ID
`app_id`	`int`	Steam application ID
`game_name`	`str`	Game name
`stats`	`list[StatEntry]`	User's stat entries

Search models¶

SearchResult¶

Returned by search().

Field	Type	Description
`term`	`str`	Search query
`total`	`int`	Number of results
`entries`	`list[SearchEntry]`	Search results

SearchEntry¶

Field	Type	Description
`app_id`	`int`	Steam application ID
`name`	`str`	Game name
`icon`	`str \\| None`	Thumbnail URL
`price`	`str \\| None`	Formatted price string
`platforms`	`Platforms \\| None`	Supported platforms

User models¶

UserProfile¶

Returned by get_user_profile().

Field	Type	Description
`steam_id`	`str`	Steam 64-bit user ID
`username`	`str`	Display name
`real_name`	`str \\| None`	Real name (if public)
`avatar`	`Avatar`	Avatar URLs
`profile_url`	`HttpUrl`	Steam community profile URL
`country_code`	`str \\| None`	ISO 3166-1 alpha-2 country code
`state_code`	`str \\| None`	State/province code
`time_created`	`int \\| None`	Account creation (Unix timestamp)
`last_logoff`	`int \\| None`	Last logoff (Unix timestamp)
`is_public`	`bool`	Whether the profile is public
`persona_state`	`int \\| None`	Online status (0=Offline, 1=Online, etc.)
`game_id`	`str \\| None`	App ID of currently played game
`game_extra_info`	`str \\| None`	Name of currently played game

Avatar¶

Field	Type	Description
`small`	`HttpUrl`	32x32 avatar
`medium`	`HttpUrl`	64x64 avatar
`full`	`HttpUrl`	184x184 avatar

UserLibrary¶

Returned by get_user_library().

Field	Type	Description
`steam_id`	`str`	Steam 64-bit user ID
`game_count`	`int`	Total games owned
`games`	`list[LibraryGame]`	Games in library

LibraryGame¶

Field	Type	Default	Description
`app_id`	`int`		Steam application ID
`name`	`str \\| None`	`None`	Game name
`playtime_forever`	`int`	`0`	Total playtime (minutes)
`playtime_2weeks`	`int \\| None`	`None`	Playtime last 2 weeks (minutes)
`img_icon_url`	`str \\| None`	`None`	Game icon image hash
`icon_url`	`str \\| None`		Computed full icon URL from `app_id` and `img_icon_url`
`last_played`	`int \\| None`	`None`	Last play session (Unix timestamp)

GameAchievements¶

Returned by get_user_achievements().

Field	Type	Description
`app_id`	`int`	Steam application ID
`game_name`	`str`	Game name
`achievements`	`list[Achievement]`	List of achievements

Achievement¶

Field	Type	Description
`api_name`	`str`	Achievement API name
`achieved`	`bool`	Whether unlocked
`unlock_time`	`int \\| None`	Unlock timestamp
`name`	`str \\| None`	Display name
`description`	`str \\| None`	Achievement description

Friend¶

A single friend entry. Returned inside FriendList.

Field	Type	Description
`steam_id`	`str`	Friend's Steam 64-bit ID
`relationship`	`str`	Relationship type (e.g. `"friend"`)
`friend_since`	`int`	Friendship start (Unix timestamp)

FriendList¶

Returned by get_user_friends().

Field	Type	Description
`steam_id`	`str`	Steam 64-bit user ID
`friends`	`list[Friend]`	List of friends

PlayerBan¶

Ban information for a user. Returned by get_user_bans().

Field	Type	Description
`steam_id`	`str`	Steam 64-bit user ID
`community_banned`	`bool`	Whether community banned
`vac_banned`	`bool`	Whether VAC banned
`number_of_vac_bans`	`int`	Total VAC bans
`days_since_last_ban`	`int`	Days since last ban
`number_of_game_bans`	`int`	Total game bans
`economy_ban`	`str`	Economy ban status

RecentGame¶

A recently played game entry. Returned inside RecentlyPlayed.

Field	Type	Description
`app_id`	`int`	Steam application ID
`name`	`str`	Game name
`playtime_2weeks`	`int`	Playtime last 2 weeks (minutes)
`playtime_forever`	`int`	Total playtime (minutes)
`img_icon_url`	`str`	Game icon URL

RecentlyPlayed¶

Returned by get_recently_played().

Field	Type	Description
`steam_id`	`str`	Steam 64-bit user ID
`total_count`	`int`	Total number of recently played games
`games`	`list[RecentGame]`	Recently played games

Badge¶

A single badge entry. Returned inside UserBadges.

Field	Type	Description
`badge_id`	`int`	Badge ID
`level`	`int`	Badge level
`completion_time`	`int`	Completion timestamp (Unix)
`xp`	`int`	XP granted by badge
`scarcity`	`int`	Number of users with this badge

UserBadges¶

Returned by get_user_badges().

Field	Type	Description
`steam_id`	`str`	Steam 64-bit user ID
`badges`	`list[Badge]`	List of badges
`player_xp`	`int`	Total player XP
`player_level`	`int`	Current Steam level

WishlistItem¶

A single wishlist entry. Returned by get_wishlist().

Field	Type	Description
`app_id`	`int`	Steam application ID
`priority`	`int`	Wishlist priority (0 = default)
`date_added`	`int`	Date added (Unix timestamp)

News models¶

NewsItem¶

A single news article. Returned inside AppNews.

Field	Type	Description
`gid`	`str`	Unique news item ID
`title`	`str`	Article title
`url`	`str`	Article URL
`author`	`str`	Author name
`contents`	`str`	Article content (may be truncated by `max_length`)
`date`	`int`	Publication date (Unix timestamp)
`feed_name`	`str`	Feed name (e.g. `"steam_community_announcements"`)

AppNews¶

Returned by get_news().

Field	Type	Description
`app_id`	`int`	Steam application ID
`items`	`list[NewsItem]`	News articles