# Steam API wrappers

## Low level methods

You can call any method from any of Steam API interfaces using `steam.api.interface` class. Let’s start with a quick example where we fetch user’s game library.

Start by importing `interface` class:

    >>> from steam.api import interface

Call method `GetOwnedGames` of interface `IPlayerService`. We are going to fetch games of user with id `76561198017493014` and include all application information:

    >>> games = interface('IPlayerService').GetOwnedGames(steamid=76561198017493014, include_appinfo=1)

Since all method calls are lazy by default, this doesn’t do anything at all. We’ll need to either iterate over `games`, `print` it or access any of its dictionary keys:

    >>> print(games['response']['game_count'])  # Fetches resource
    249

Don’t worry, resource isn’t fetched each time you access results.

    >>> print(games)  # Uses cached resource
    {'response': {'games': [{'name': 'Counter-Strike', 'playtime_forever': 1570,...

You can disable laziness of `interface` by passing `aggressive=True` to its method:

    >>> games = interface('IPlayerService').GetOwnedGames(steamid=76561198017493014, include_appinfo=1, aggressive=True)

You can also pass `since` (which translates to HTTP header `If-Modified-Since`) and `timeout` to method. By default, `version` is set to `1`. `data` can be passed to send POST data with requests. By default no data is assumed and request types are GET. Any number of additional keyword arguments are supported depending on the given method (see documentation).

## High level methods

Following classes are convenience wrappers around Low level methods. `kwargs` are always passed to appropriate interface methods, so you can use all arguments from previous section.

### Apps

class steam.apps.app_list(**kwargs)

  Retrieves a list of all Steam apps with their ID and localized name.

      >>> from steam.apps import app_list
      >>> app_list = app_list()
      >>> 'Dota 2' in app_list
      True
      >>> 'Half-Life 3' in app_list
      False
      >>> len(app_list)
      16762
      >>> app_list['Counter-Strike']
      (10, u'Counter-Strike')

### Items

class steam.items.schema(app, lang=None, version=1, **kwargs)

  Wrapper for item schema of certain games from Valve. Those are currently available (along with their ids):

  > - `260` - Counter Strike: Source Beta

  > - `440` - Team Fortress 2

  > - `520` - Team Fortress 2 Public Beta

  > - `570` - Dota 2

  > - `620` - Portal 2

  > - `710` - Counter-Strike: Global Offensive Beta Dev

  > - `816` - Dota 2 internal test

  > - `841` - Portal 2 Beta

  > - `205790` - Dota 2 (beta) test

  Fetching schema of Team Fortress 2 (id `440`) would look like:

      >>> schema = steam.items.schema(440)
      >>> schema[340].name
      u'Defiant Spartan'

  Schema class is an iterator of `steam.items.item()` objects. There are also other properties available:

  client_url

    Client schema URL

  language

    The ISO code of the language the instance is localized to

  attributes

    Returns all attributes in the schema

  origins

    Returns a map of all origins

  qualities

    Returns a dict of all possible qualities. The key(s) will be the ID, values are a tuple containing ID, name, localized name. To resolve a quality to a name intelligently use ‘_quality_definition’

  particle_systems

    Returns a dictionary of particle system dicts keyed by ID

  kill_ranks

    Returns a list of ranks for weapons with kill tracking

  kill_types

    Returns a dict with keys that are the value of the kill eater type attribute and values that are the name string

class steam.items.item(item, schema=None)

  Stores a single inventory item.

  This is a simple wrapper around JSON representation of both schema and inventory items. It is composed mostly from item properties:

      >>> item = schema[340]
      >>> item.name
      u'Defiant Spartan'
      >>> item.type
      u'Hat'
      >>> item.attributes
      [<steam.items.item_attribute object at 0x10c8b3290>, <steam.items.item_attribute object at 0x10c8b3210>]

  As convenience, `item` acts also as iterator of its attributes:

      >>> for attribute in item.attributes:
      ...     attribute.name
      ...
      u'kill eater score type'
      u'kill eater kill type'

  Following properties are available:

  attributes

    Returns a list of attributes

  quality

    Returns a tuple containing ID, name, and localized name of the quality

  inventory_token

    Returns the item’s inventory token (a bitfield), deprecated.

  position

    Returns a position in the inventory or -1 if there’s no position available (i.e. an item hasn’t dropped yet or got displaced)

  equipped

    Returns a dict of classes that have the item equipped and in what slot

  equipable_classes

    Returns a list of classes that _can_ use the item.

  schema_id

    Returns the item’s ID in the schema.

  name

    Returns the item’s undecorated name

  type

    Returns the item’s type. e.g. “Kukri” for the Tribalman’s Shiv. If Valve failed to provide a translation the type will be the token without the hash prefix.

  icon

    URL to a small thumbnail sized image of the item, suitable for display in groups

  image

    URL to a full sized image of the item, for displaying ‘zoomed-in’ previews

  id

    Returns the item’s unique serial number if it has one

  original_id

    Returns the item’s original ID if it has one. This is the last “version” of the item before it was customized or otherwise changed

  level

    Returns the item’s level (e.g. 10 for The Axtinguisher) if it has one

  slot_name

    Returns the item’s slot as a string, this includes “primary”, “secondary”, “melee”, and “head”. Note that this is the slot of the item as it appears in the schema, and not necessarily the actual equipable slot. (see ‘equipped’)

  cvar_class

    Returns the item’s class (what you use in the game to equip it, not the craft class)

  craft_class

    Returns the item’s class in the crafting system if it has one. This includes hat, craft_bar, or craft_token.

  craft_material_type
  custom_name

    Returns the item’s custom name if it has one.

  custom_description

    Returns the item’s custom description if it has one.

  quantity

    Returns the number of uses the item has, for example, a dueling mini-game has 5 uses by default

  description

    Returns the item’s default description if it has one

  min_level

    Returns the item’s minimum level (non-random levels will have the same min and max level)

  contents

    Returns the item in the container, if there is one. This will be a standard item object.

  tradable

    Somewhat of a WORKAROUND since this flag is there sometimes, “cannot trade” is there sometimes and then there’s “always tradable”. Opposed to only occasionally tradable when it feels like it. Attr 153 = cannot trade

  craftable

    Returns not craftable if the cannot craft flag exists. True, otherwise.

  full_name

    The full name of the item, generated depending on things such as its quality, rank, the schema language, and so on.

  kill_eaters

    Returns a list of tuples containing the proper localized kill eater type strings and their values according to set/type/value “order”

  rank

    Returns the item’s rank (if it has one) as a dict that includes required score, name, and level.

  available_styles

    Returns a list of all styles defined for the item

  style

    The current style the item is set to or None if the item has no styles

  capabilities

    Returns a list of capabilities, these are flags for what the item can do or be done with

  tool_metadata

    A dict containing item dependant metadata such as holiday restrictions, types, and properties used by the client. Do not assume a stable syntax.

  origin

    Returns the item’s localized origin name

class steam.items.item_attribute(attribute)

  Wrapper around item attributes.

      >>> for attribute in item.attributes:
      ...     print('%s: %s' % (attribute.name, attribute.formatted_value))
      ...
      kill eater score type: 64.0
      kill eater kill type: 64.0

  Following properties are available:

  formatted_value

    Returns a formatted value as a string

  formatted_description

    Returns a formatted description string (%s* tokens replaced) or None if unavailable

  name

    The attribute’s name

  cvar_class

    The attribute class, mostly non-useful except for console usage in some cases

  id

    The attribute ID, used for indexing the description blocks in the schema

  type

    Returns the attribute effect type (positive, negative, or neutral). This is not the same as the value type, see ‘value_type’

  value

    Tries to intelligently return the raw value based on schema data. See also: ‘value_int’ and ‘value_float’

  value_int
  value_float
  description

    Returns the attribute’s description string, if it is intended to be printed with the value there will be a “%s1” token somewhere in the string. Use ‘formatted_description’ to build one automatically.

  value_type

    The attribute’s type, note that this is the type of the attribute’s value and not its affect on the item (i.e. negative or positive). See ‘type’ for that.

  hidden

    True if the attribute is “hidden” (not intended to be shown to the end user). Note that hidden attributes also usually have no description string

  account_info

    Certain attributes have a user’s account information associated with it such as a gifted or crafted item.

    A dict with two keys: ‘persona’ and ‘id64’. None if the attribute has no account information attached to it.

class steam.items.inventory(profile, app, schema=None, **kwargs)

  Wrapper around player inventory.

  Fetches inventory of `player` for given `app` id:

      >>> inventory = steam.items.inventory(76561198017493014, 570)
      >>> for item in inventory:
      ...     item.name
      ...
      '226749283'
      '226749284'

  Since inventory endpoint returns just very basic structure, we have to provide also `schema` if we want to work with fully populated `steam.items.item()` objects:

      >>> schema = steam.items.schema(440)
      >>> inventory = steam.items.inventory(76561198017493014, 440, schema)
      >>> for item in inventory:
      ...     item.name
      ...
      u'Mercenary'
      u'Noise Maker - Winter Holiday'

  There is also single property:

  cells_total

    The total number of cells in the inventory. This can be used to determine if the user has bought an expander. This is NOT the number of items in the inventory, but how many items CAN be stored in it. The actual current inventory size can be obtained by calling len on an inventory object

class steam.items.assets(app, lang=None, **kwargs)

  Class for building asset catalogs

  Fetches store assets for `app` id. Assets class acts as an iterator of `steam.items.asset_item()` objects.

      >>> assets = steam.items.assets(440)
      >>> for asset in assets:
      ...     asset.price
      ...
      {u'MXN': 74.0, u'EUR': 4.59, u'VND': 109000.0, u'AUD': 6.5, ...}
      {u'MXN': 112.0, u'EUR': 6.99, u'VND': 159000.0, u'AUD': 9.8, ...}

  If you care only about single currency, `currency` keyword argument in ISO 4217 format is also accepted.

      >>> assets = steam.items.assets(440, currency="RUB")
      >>> for asset in assets:
      ...     asset.price
      ...
      {u'RUB': 290.0}
      {u'RUB': 435.0}

  All available tags of assets are available in following property:

  tags

    Returns a dict that is a map of the internal tag names for this catalog to the localized labels.

class steam.items.asset_item(asset, catalog)

  Stores a single item from a steam asset catalog

  tags

    Returns a dict containing tags and their localized labels as values

  base_price

    The price the item normally goes for, not including discounts.

  price

    Returns the most current price available, which may include sales/discounts

  name

    The asset “name” which is in fact a schema id of item.

### Localization

class steam.loc.language(code=None)

  Steam API localization tools and reference

      >>> language = steam.loc.language('nl_NL')
      >>> language.name
      'Dutch'
      >>> language.code
      'nl_NL'

  If language is not specified, it defaults to English:

      >>> language = steam.loc.language()
      >>> language.name
      'English'
      >>> language.code
      'en_US'

  If language isn’t supported, `__init__` raises `steam.loc.LanguageUnsupportedError()`

      >>> language = steam.loc.language('sk_SK')
      Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "steam/loc.py", line 68, in __init__
          raise LanguageUnsupportedError(code)
      steam.loc.LanguageUnsupportedError: sk_sk

  Properties:

  code
  name

class steam.loc.LanguageUnsupportedError

### Remote storage

Tools for probing Steam’s UGC file storage system. UGC itself means User Generated Content but in this context assume that such terms as “UGC ID” are specific to Valve’s system. UGC IDs are found in various places in the API and Steam including decal attributes on TF2 items.

Practically speaking the purpose of ugc_file is similar to that of `steam.user.vanity_url`. Namely to convert an arbitrary ID into something useful like a direct URL.

class steam.remote_storage.ugc_file(appid, ugcid64, **kwargs)

  Resolves a UGC file ID into usable metadata.

  Fetches UGC file metadata for the given UGC and app ID.

      >>> ugc = steam.remote_storage.ugc_file(440, 650994986817657344)
      >>> ugc.url
      u'http://images.akamai.steamusercontent.com/ugc/650994986817657344/D2ADAD7F19BFA9A99BD2B8850CC317DC6BA01BA9/'

  Properties:

  size

    Size in bytes

  filename

    Local filename is what the user named it, not the URL

  url

    UGC link

class steam.remote_storage.FileNotFoundError

### User

class steam.user.vanity_url(vanity, **kwargs)

  Class for holding a vanity URL and its id64

      >>> vanity_url = steam.user.vanity_url('http://steamcommunity.com/id/ondrowan')
      >>> vanity_url.id64
      76561198017493014

class steam.user.profile(sid, **kwargs)

  Functions for reading user account data

      >>> profile = steam.user.profile('76561198017493014')
      >>> profile.persona
      u'Lich Buchannon'
      >>> profile.level
      37

  id64

    Returns the 64 bit steam ID (use with other API requests)

  id32

    Returns the 32 bit steam ID

  persona

    Returns the user’s persona (what you usually see in-game)

  profile_url

    Returns a URL to the user’s Community profile page

  vanity

    Returns the user’s vanity url if it exists, None otherwise

  avatar_small
  avatar_medium
  avatar_large
  status

    Returns the user’s status. 0: offline 1: online 2: busy 3: away 4: snooze 5: looking to trade 6: looking to play If player’s profile is private, this will always be 0.

  visibility

    Returns the visibility setting of the profile. 1: private 2: friends only 3: public

  configured

    Returns true if the user has created a Community profile

  last_online

    Returns the last time the user was online as a localtime time.struct_time struct

  comments_enabled

    Returns true if the profile allows public comments

  real_name

    Returns the user’s real name if it’s set and public

  primary_group

    Returns the user’s primary group ID if set.

  creation_date

    Returns the account creation date as a localtime time.struct_time struct if public

  current_game

    Returns a tuple of 3 elements (each of which may be None if not available): Current game app ID, server ip:port, misc. extra info (eg. game title)

  location

    Returns a tuple of 2 elements (each of which may be None if not available): State ISO code, country ISO code

  lobbysteamid

    Returns a lobbynumber as int from few Source games or 0 if not in lobby.

  level

    Returns the the user’s profile level, note that this runs a separate request because the profile level data isn’t in the standard player summary output even though it should be. Which is also why it’s not implemented as a separate class. You won’t need this output and not the profile output

  classmethod from_def(obj)

    Builds a profile object from a raw player summary object

  current_game

    Returns a tuple of 3 elements (each of which may be None if not available): Current game app ID, server ip:port, misc. extra info (eg. game title)

class steam.user.profile_batch(sids)

      >>> profiles = steam.user.profile_batch(['76561198811195748', '76561198017493014'])
      >>> for profile in profiles:
      ...     profile.persona
      ...
      u'Bot.Lagg.Me Space Cadet 01'
      u'Lich Buchannon'

class steam.user.bans(sid, **kwargs)

      >>> bans = steam.user.bans('76561197962899758')
      >>> bans.vac
      True
      >>> bans.vac_count
      1
      >>> bans.days_unbanned
      2708

  id64
  community

    Community banned

  vac

    User is currently VAC banned

  vac_count

    Number of VAC bans on record

  days_unbanned

    Number of days since the last ban. Note that users without a ban on record will have this set to 0 so make sure to test bans.vac

  economy

    Economy ban status which is a string for whatever reason

  game_count

    Number of bans in games, this includes CS:GO Overwatch bans

  classmethod from_def(obj)

class steam.user.bans_batch(sids)

      >>> bans_batch = steam.user.bans_batch(['76561197962899758', '76561198017493014'])
      >>> for bans in bans_batch:
      ...     '%s: %s' % (bans.id64, bans.vac)
      ...
      '76561197962899758: True'
      '76561198017493014: False'

class steam.user.friend(friend_dict)

  Class used to store friend obtained from GetFriendList.

  steamid

    Returns the 64 bit Steam ID

  relationship

    Returns relationship qualifier

  since

    Returns date when relationship was created as a localtime time.struct_time

class steam.user.friend_list(sid, relationship='all', **kwargs)

  Creates an iterator of friend objects fetched from given user’s Steam ID. Allows for filtering by specyfing relationship argument in constructor, but API seems to always return items with friend relationship. Possible filter values: all, friend.

      >>> friend_list = steam.user.friend_list('76561198811195748')
      >>> friend_list.count
      146
      >>> for friend in friend_list:
      ...     friend.steamid
      ...
      76561197960299337
      76561197960339433
      (... and 144 more)

  count

    Returns number of friends