Steam Web API

The Steam Web API provides a mechanism to use Steam services over an HTTP. The API is divided up into “interfaces” with each interface having a number of methods that can be performed on it. Python-valve provides a thin wrapper on top of these interfaces as well as a higher-level implementation.

Generally you’ll want to use the higher-level interface to the API as it provides greater abstraction and session management. However the higher-level API only covers a few core interfaces of the Steam Web API, so it may be necessary to use the wrapper layer in some circumstances.

Although an API key is not strictly necessary to use the Steam Web API, it is advisable to get an API key. Using an API key allows access to greater functionality. Also, before using the Steam Web API it is good idea to read the Steam Web API Terms of Use and Steam Web API Documentation.

Low-level Wrapper

The Steam Web API is self-documenting via the /ISteamWebAPIUtil/GetSupportedAPIList/v1/ endpoint. This enables python-valve to build the wrapper entirely automatically, which includes validating parameters and automatic generation of documentation.

The entry-point for using the API wrapper is by constructing a API instance. During initialisation a request is issued to the GetSupportedAPIList endpoint and the interfaces are constructed. If a Steam Web API key is specified then a wider selection of interfaces will be available. Note that this can be a relatively time consuming process as the response returned by GetSupportedAPIList can be quite large. This is especially true when an API key is given as there are more interfaces to generated.

An instance of each interface is created and bound to the API instance, as it is this API instance that will be responsible for dispatching the HTTP requests. The interfaces are made available via API.__getitem__(). The interface objects have methods which correspond to those returned by GetSupportedAPIList.

class valve.steam.api.interface.API(key=None, format=u'json', versions=None, interfaces=None)
__getitem__(interface_name)

Get an interface instance by name

__init__(key=None, format=u'json', versions=None, interfaces=None)

Initialise an API wrapper

The API is usable without an API key but exposes significantly less functionality, therefore it’s advisable to use a key.

Response formatters are callables which take the Unicode response from the Steam Web API and turn it into a more usable Python object, such as dictionary. The Steam API it self can generate responses in either JSON, XML or VDF. The formatter callables should have an attribute format which is a string indicating which textual format they handle. For convenience the format parameter also accepts the strings json, xml and vdf which are mapped to the json_format(), etree_format() and vdf_format() formatters respectively.

The interfaces argument can optionally be set to a module containing BaseInterface subclasses which will be instantiated and bound to the API instance. If not given then the interfaces are loaded using ISteamWebAPIUtil/GetSupportedAPIList.

The optional versions argument allows specific versions of interface methods to be used. If given, versions should be a mapping of further mappings keyed against the interface name. The inner mapping should specify the version of interface method to use which is keyed against the method name. These mappings don’t need to be complete and can omit methods or even entire interfaces. In which case the default behaviour is to use the method with the highest version number.

Parameters:
  • key (str) – a Steam Web API key.
  • format – response formatter.
  • versions – the interface method versions to use.
  • interfaces – a module containing BaseInterface subclasses or None if they should be loaded for the first time.
api_root = u'https://api.steampowered.com/'
request(http_method, interface, method, version, params=None, format=None)

Issue a HTTP request to the Steam Web API

This is called indirectly by interface methods and should rarely be called directly. The response to the request is passed through the response formatter which is then returned.

Parameters:
  • interface (str) – the name of the interface.
  • method (str) – the name of the method on the interface.
  • version (int) – the version of the method.
  • params – a mapping of GET or POST data to be sent with the request.
  • format – a response formatter callable to overide format.
session(*args, **kwds)

Create an API sub-session without rebuilding the interfaces

This returns a context manager which yields a new API instance with the same interfaces as the current one. The difference between this and creating a new API manually is that this will avoid rebuilding the all interface classes which can be slow.

versions()

Get the versions of the methods for each interface

This returns a dictionary of dictionaries which is keyed against interface names. The inner dictionaries map method names to method version numbers. This structure is suitable for passing in as the versions argument to __init__().

Interface Method Version Pinning

It’s important to be aware of the fact that API interface methods can have multiple versions. For example, ISteamApps/GetAppList. This means they may take different arguments and returned different responses. The default behaviour of the API wrapper is to always expose the method with the highest version number.

This is fine in most cases, however it does pose a potential problem. New versions of interface methods are likely to break backwards compatability. Therefore API provides a mechanism to manually specify the interface method versions to use via the versions argument to API.__init__().

The if given at all, versions is expected to be a dictionary of dictionaries keyed against interface names. The inner dictionaries map method names to versions. For example:

{"ISteamApps": {"GetAppList": 1}}

Passsing this into API.__init__() would mean version 1 of ISteamApps/GetAppList would be used in preference to the default behaviour of using the highest version – wich at the time of writing is version 2.

It is important to pin your interface method versions when your code enters production or otherwise face the risk of it breaking in the future if and when Valve updates the Steam Web API. The API.pin_versions() method is provided to help in determining what versions to pin. How to integrate interface method version pinning into existing code is an excerise for the reader however.

Response Formatters

valve.steam.api.interface.json_format(response)

Parse response as JSON using the standard Python JSON parser

Returns:the JSON object encoded in the response.
valve.steam.api.interface.etree_format(response)

Parse response using ElementTree

Returns:a xml.etree.ElementTree.Element of the root element of the response.
valve.steam.api.interface.vdf_format(response)

Parse response using valve.vdf

Returns:a dictionary decoded from the VDF.

Interfaces

These interfaces are automatically wrapped and documented. The availability of some interfaces is dependant on whether or not an API key is given. It should also be noted that as the interfaces are generated automatically they do not respect the naming conventions as detailed in PEP 8.

class interfaces.IGCVersion_205790(api)
GetClientVersion()
GetServerVersion()
name = u'IGCVersion_205790'
class interfaces.IGCVersion_440(api)
GetClientVersion()
GetServerVersion()
name = u'IGCVersion_440'
class interfaces.IGCVersion_570(api)
GetClientVersion()
GetServerVersion()
name = u'IGCVersion_570'
class interfaces.IGCVersion_730(api)
GetServerVersion()
name = u'IGCVersion_730'
class interfaces.IPortal2Leaderboards_620(api)
GetBucketizedData(leaderboardName)
Parameters:leaderboardName (string) – The leaderboard name to fetch data for.
name = u'IPortal2Leaderboards_620'
class interfaces.IPortal2Leaderboards_841(api)
GetBucketizedData(leaderboardName)
Parameters:leaderboardName (string) – The leaderboard name to fetch data for.
name = u'IPortal2Leaderboards_841'
class interfaces.ISteamApps(api)
GetAppList()
GetServersAtAddress(addr)
Parameters:addr (string) – IP or IP:queryport to list
UpToDateCheck(appid, version)
Parameters:
  • appid (uint32) – AppID of game
  • version (uint32) – The installed version of the game
name = u'ISteamApps'
class interfaces.ISteamDirectory(api)
GetCMList(cellid, maxcount=None)
Parameters:
  • cellid (uint32) – Client’s Steam cell ID
  • maxcount (uint32) – Max number of servers to return
name = u'ISteamDirectory'
class interfaces.ISteamEnvoy(api)
PaymentOutNotification()
PaymentOutReversalNotification()
name = u'ISteamEnvoy'
class interfaces.ISteamNews(api)
GetNewsForApp(appid, count=None, enddate=None, feeds=None, maxlength=None)
Parameters:
  • appid (uint32) – AppID to retrieve news for
  • count (uint32) – # of posts to retrieve (default 20)
  • enddate (uint32) – Retrieve posts earlier than this date (unix epoch timestamp)
  • feeds (string) – Comma-seperated list of feed names to return news for
  • maxlength (uint32) – Maximum length for the content to return, if this is 0 the full content is returned, if it’s less then a blurb is generated to fit.
name = u'ISteamNews'
class interfaces.ISteamPayPalPaymentsHub(api)
PayPalPaymentsHubPaymentNotification()
name = u'ISteamPayPalPaymentsHub'
class interfaces.ISteamRemoteStorage(api)
GetCollectionDetails(collectioncount, publishedfileids0)
Parameters:
  • collectioncount (uint32) – Number of collections being requested
  • publishedfileids0 (uint64) – collection ids to get the details for
GetPublishedFileDetails(itemcount, publishedfileids0)
Parameters:
  • itemcount (uint32) – Number of items being requested
  • publishedfileids0 (uint64) – published file id to look up
name = u'ISteamRemoteStorage'
class interfaces.ISteamUserAuth(api)
AuthenticateUser(encrypted_loginkey, sessionkey, steamid)
Parameters:
  • encrypted_loginkey (rawbinary) – Should be the users hashed loginkey, AES encrypted with the sessionkey.
  • sessionkey (rawbinary) – Should be a 32 byte random blob of data, which is then encrypted with RSA using the Steam system’s public key. Randomness is important here for security.
  • steamid (uint64) – Should be the users steamid, unencrypted.
name = u'ISteamUserAuth'
class interfaces.ISteamUserOAuth(api)
GetTokenDetails(access_token)
Parameters:access_token (string) – OAuth2 token for which to return details
name = u'ISteamUserOAuth'
class interfaces.ISteamUserStats(api)
GetGlobalAchievementPercentagesForApp(gameid)
Parameters:gameid (uint64) – GameID to retrieve the achievement percentages for
GetGlobalStatsForGame(appid, count, name0, enddate=None, startdate=None)
Parameters:
  • appid (uint32) – AppID that we’re getting global stats for
  • count (uint32) – Number of stats get data for
  • enddate (uint32) – End date for daily totals (unix epoch timestamp)
  • name0 (string) – Names of stat to get data for
  • startdate (uint32) – Start date for daily totals (unix epoch timestamp)
GetNumberOfCurrentPlayers(appid)
Parameters:appid (uint32) – AppID that we’re getting user count for
name = u'ISteamUserStats'
class interfaces.ISteamWebAPIUtil(api)
GetServerInfo()
GetSupportedAPIList()
name = u'ISteamWebAPIUtil'
class interfaces.ISteamWebUserPresenceOAuth(api)
PollStatus(message, steamid, umqid, pollid=None, secidletime=None, sectimeout=None, use_accountids=None)
Parameters:
  • message (uint32) – Message that was last known to the user
  • pollid (uint32) – Caller-specific poll id
  • secidletime (uint32) – How many seconds is client considering itself idle, e.g. screen is off
  • sectimeout (uint32) – Long-poll timeout in seconds
  • steamid (string) – Steam ID of the user
  • umqid (uint64) – UMQ Session ID
  • use_accountids (uint32) – Boolean, 0 (default): return steamid_from in output, 1: return accountid_from
name = u'ISteamWebUserPresenceOAuth'
class interfaces.IPlayerService(api)
RecordOfflinePlaytime(play_sessions, steamid, ticket)
Parameters:
  • play_sessions (string) –
  • steamid (uint64) –
  • ticket (string) –
name = u'IPlayerService'
class interfaces.IAccountRecoveryService(api)
ReportAccountRecoveryData(install_config, loginuser_list, machineid, shasentryfile)
Parameters:
  • install_config (string) –
  • loginuser_list (string) –
  • machineid (string) –
  • shasentryfile (string) –
RetrieveAccountRecoveryData(requesthandle)
Parameters:requesthandle (string) –
name = u'IAccountRecoveryService'