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 theformat
parameter also accepts the stringsjson
,xml
andvdf
which are mapped to thejson_format()
,etree_format()
andvdf_format()
formatters respectively.The
interfaces
argument can optionally be set to a module containingBaseInterface
subclasses which will be instantiated and bound to theAPI
instance. If not given then the interfaces are loaded usingISteamWebAPIUtil/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 orNone
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 newAPI
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.
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'¶
-