Difference between revisions of "WebAPI"

From Team Fortress Wiki
Jump to: navigation, search
(Result layout: Promotion and store flags)
m
 
(96 intermediate revisions by 22 users not shown)
Line 1: Line 1:
The Steam Web API is documented at http://steamcommunity.com/dev and http://developer.valvesoftware.com/wiki/Steam_Web_API. The mapping of the API data to each data format is described on the latter.
+
== Contributing ==
  
This page documents the web API calls that allow you to retrieve information from the item system in Team Fortress 2.
+
If you would like to help in writing API documentation there is a tool available [https://github.com/Lagg/steam-swissapiknife here] (requires python) that can generate skeleton documentation pages
 +
that match the style guidelines and can be easily copied and pasted.
  
Calls to the TF2 Web API require a valid Steam Web API key to function. You can get your own API Key [http://www.steamcommunity.com/dev/apikey here]. Each example URL will only work after replacing "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" with your API key.
+
Otherwise be sure to follow the existing structure and format of the documentation to keep things consistent.
  
 
== Common elements ==
 
== Common elements ==
  
=== Arguments ===
+
=== Parameters ===
  
All TF2 methods take the following arguments in their URL:
+
Most WebAPI methods take the following arguments in their URL:
  
*'''key''': Your Steam Web API key. Without this, the server will return a 403 Forbidden HTTP status.
+
;key: Your Steam Web API key. Without this, the server will return an HTTP 403 (forbidden) error. A key can be generated [http://www.steamcommunity.com/dev/apikey here].
*'''format''' ''(optional)'': The format to return the data in ("'''<tt>json</tt>'''" for JSON, "'''<tt>xml</tt>'''" for XML, or "'''<tt>vdf</tt>'''" for VDF). The structure of the data for each format is described at
+
;{{API optional|format}}: The file format to return output in.
http://developer.valvesoftware.com/wiki/Steam_Web_API#Formats. If no format is specified, the data will be returned with the default of JSON.
+
:;<code>json</code> (default): The [https://www.json.org/json-en.html JavaScript Object Notation] format
 
+
:;<code>xml</code>: Standard XML
=== Result structure ===
+
:;<code>vdf</code>: [[WebAPI/VDF|Valve Data Format]]
 
+
;{{API optional|language}}
All TF2 methods return a "'''<tt>result</tt>'''" object containing a status code (at "'''<tt>status</tt>'''") and either the data requested or a status message explaining why the data was not returned (at "'''<tt>statusDetail</tt>'''").
+
:The [[w:List of ISO 639-1 codes|ISO639-1 language code]] for the language all tokenized strings should be returned in. Not all strings have been translated to every language. If a language does not have a string, the English string will be returned instead. If this parameter is omitted the string token will be returned for the strings.
  
 
=== Terminology ===
 
=== Terminology ===
  
A "tokenized string" refers to a string containing "#"-prefixed tokens that are replaced with the equivalent string in the game's VDF for the chosen language. For instance, "<tt>TF_Weapon_Jar</tt>" is defined as "<tt>[[Jarate|Jar Based Karate]]</tt>" in tf/resource/tf_english.txt (as found in "team fortress 2 content.gcf").
+
A "tokenized string" refers to a string containing "<code>#</code>"-prefixed tokens that are replaced with the equivalent string in the game's VDF for the chosen language. For instance, "<code>TF_Weapon_Jar</code>" is defined as "<code>[[Jarate|Jar Based Karate]]</code>" in tf/resource/tf_english.txt (as found in "team fortress 2 content.gcf").
 
 
== GetSchema (v0001) ==
 
 
 
This method returns the item schema for the current build of Team Fortress 2.
 
 
 
Example URL: http://api.steampowered.com/ITFItems_440/GetSchema/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&format=json
 
=== Arguments ===
 
language - The [[Wikipedia:List of ISO 639-1 codes|ISO639-1 language code]] for the language all localized strings should be returned in. Not all strings have been translated to every language. If a language does not have a string, the English string will be returned instead.  If this parameter is omitted the string token will be returned for the strings.
 
 
 
Supported languages for TF2 are:
 
* Danish (da)
 
* Dutch (nl)
 
* English (en)
 
* Finnish (fi)
 
* French (fr)
 
* German (de)
 
* Italian (it)
 
* Japanese (ja)
 
* Korean (ko)
 
* Norwegian (no)
 
* Polish (pl)
 
* Portuguese (pt)
 
* Russian (ru)
 
* Simplified Chinese (zh - hides Traditional Chinese)
 
* Spanish (es)
 
* Swedish (sv)
 
* Traditional Chinese (Cannot be specified by ISO639-1)
 
 
 
=== Status codes ===
 
 
 
*'''<tt>1</tt>''': The normal code. Should always be returned.
 
 
 
=== Result data ===
 
 
 
*"'''<tt>qualities</tt>'''": An object containing the numeric values corresponding to each "quality" an item can have (excluding three entries for the standard Medic weapons between the standard weapons and the unlockable weapons, which have the unlisted quality of 255):
 
**"'''<tt>normal</tt>'''" ''(<tt>0</tt>)'': In the list of items returned by GetSchema, all of the standard inherent basic class weapons have this listed as their quality.
 
**"'''<tt>common</tt>'''" ''(<tt>1</tt>)'': In the list of items returned by GetSchema, no items have this listed as their quality.
 
**"'''<tt>rare</tt>'''" ''(<tt>2</tt>)'': In the list of items returned by GetSchema, no items have this listed as their quality.
 
**"'''<tt>unique</tt>'''" ''(<tt>6</tt>)'': In GetPlayerItems, all normally-obtained (not manually awarded by Valve) unlockable items have this as their quality. In the list of items returned by GetSchema, all findable items have this listed as their quality.
 
**"'''<tt>community</tt>'''" ''(<tt>7</tt>)'': In GetPlayerItems, Community items (a special kind of item, normally with special particle effects and description line, given to valuable community contributors) have this quality. In the list of items returned by GetSchema, no items have this as listed their quality.
 
**"'''<tt>developer</tt>'''" ''(<tt>8</tt>)'': In GetPlayerItems, Valve items (a special kind of item with special properties belonging only to Valve employees) have this as their quality. In the list of items returned by GetSchema, no items have this as listed their quality.
 
**"'''<tt>selfmade</tt>'''" ''(<tt>9</tt>)'': In GetPlayerItems, self-made items (items whose model was made by the player possessing the item, or Telltale Games employees in the case of the Sam & Max items, normally with a special particle effect and description line) have this as their quality. In the list of items returned by GetSchema, no items have this as listed their quality.
 
**"'''<tt>vintage</tt>'''" ''(<tt>3</tt>)'': In GetPlayerItems, vintage items (items the player had before the [[Polycount Update]]) have this as their quality.
 
**"'''<tt>customized</tt>'''" ''(<tt>10</tt>)'': In GetPlayerItems, customized items (items that have been painted or renamed) have this as their quality.
 
**"'''<tt>rarity4</tt>'''" ''(<tt>5</tt>)'': Possibly for items such as crates or gifts. English localized name is "Unusual".
 
*"'''<tt>qualityNames</tt>'''": If the language argument is specified this object is included in the output. It includes the translations of the internal quality names to the specified language.
 
*"'''<tt>items</tt>'''": An object containing an array of "'''<tt>item</tt>'''":
 
**"'''<tt>name</tt>'''": A string that defines the item in the items_game.txt
 
**"'''<tt>defindex</tt>'''": The item's unique index, used to refer to instances of the item in GetPlayerItems.
 
**"'''<tt>item_class</tt>'''": The item's class in game (ie. what you would use as the argument to "equip" in the console to equip it).
 
**"'''<tt>item_type_name</tt>'''": The tokenized string that describes the item's class (eg. "<tt>#TF_Wearable_Shield</tt>" for the [[Chargin' Targe]] and the [[Razorback]]). If the language argument is specified the string for that language will be returned instead of the token.
 
**"'''<tt>item_name</tt>'''": The tokenized string for the item's name (eg. "<tt>#TF_Spy_Camera_Beard</tt>" for the [[Camera Beard]]). If the language argument is specified the string for that language will be returned instead of the token.
 
**"'''<tt>item_slot</tt>'''": A string describing what loadout slot the item corresponds to:
 
***"''<tt>primary</tt>''" for primary slot items (including "Slot Token - Primary")
 
***"''<tt>secondary</tt>''" for secondary slot items (including "Slot Token - Secondary")
 
***"''<tt>melee</tt>''" for melee slot items (including "Slot Token - Melee")
 
***"''<tt>head</tt>''" for hats and "Slot Token - Head"
 
***"''<tt>misc</tt>''" for misc slot items such as medals
 
***"''<tt>pda</tt>''" for the Engineer's Build PDA, the Spy's Disguise Kit, and "Slot Token - PDA"
 
***"''<tt>pda2</tt>''" for the Engineer's Destroy PDA, the Spy's [[Invisibility Watch]], the [[Cloak and Dagger]], the [[Dead Ringer]], and "Slot Token - PDA2"
 
***"''<tt>Engineer</tt>''" for metal and class tokens ''(yes, all class tokens)''
 
***"''<tt>building</tt>''" for "TF_WEAPON_BUILDER" (an unused copy of the Engineer's Build PDA) and the unused "Slot Token - Building"
 
***"''<tt>grenade</tt>''" for only the unused "Slot Token - Grenade"
 
**"'''<tt>item_quality</tt>'''": The item's normal quality value. See description of "'''<tt>qualities</tt>'''" above.
 
**"'''<tt>image_inventory</tt>'''": The image to display, as an escaped-slash ("\/") path to the material, without the extension
 
**"'''<tt>image_url</tt>'''": The URL of the small (128x128) backpack icon for this kind of item.
 
**"'''<tt>image_url_large</tt>'''": The URL of the large (512x512) backpack image for this kind of item.
 
**"'''<tt>model_player</tt>'''": The model to display for the item, using a path similar to the above but with an ".mdf" extension, or null if the object has no model.
 
**"'''<tt>craft_class</tt>'''" ''(Optional)'': The type of the item from the crafting system's point of view. If this field is not present the item cannot be crafted by the random crafting recipes. This will be weapon, hat, craft_bar, or craft_token.
 
**"'''<tt>used_by_classes</tt>'''" ''(Optional)'': The list of classes that can use this item. If this field is not present all classes can use the item.
 
  
**"'''<tt>attributes</tt>'''" ''(Optional)'': If the item has effects normally associated with it, an object containing an array of "'''<tt>attribute</tt>'''":
+
== Methods ==
***"'''<tt>name</tt>'''": The attribute's "<tt>name</tt>" value ''(see below)''
+
=== General interfaces ===
***"'''<tt>class</tt>'''": The attribute's "<tt>attribute_class</tt>" value ''(see below)''
 
***"'''<tt>value</tt>'''": The "value" of that attribute as a "%0.6f" formatted number: 1 (or 0) for boolean attributes (such as the [[Razorback]]'s backstab blocking), or the multiplier for percentage-based attributes (such as 0.300000 for the [[Direct Hit]]'s 30% blast radius, or 1.800000 for its 180% projectile speed)
 
*"'''<tt>attributes</tt>'''": An object containing an array of "'''<tt>attribute</tt>'''":
 
**"'''<tt>name</tt>'''": A name describing the attribute (eg. "<tt>damage bonus</tt>" for damage increases found on weapons such as the [[Scotsman's Skullcutter]], or "<tt>scattergun has knockback</tt>" for the [[Force-A-Nature]]'s knockback)
 
**"'''<tt>defindex</tt>'''": The attribute's unique index, possibly used to refer to unique instances of the item with these attributes in GetPlayerItems.
 
**"'''<tt>attribute_class</tt>'''": an underscore-based name for the attribute (eg. "<tt>mult_dmg</tt>" for the attribute whose <tt>name</tt> is "<tt>damage bonus</tt>")
 
**"'''<tt>minvalue</tt>'''": The minimum value allowed for this attribute.
 
**"'''<tt>maxvalue</tt>'''": The maximum value allowed for this attribute.
 
*** Note that values found on items are not guaranteed to fall within this range: for instance, "attach particle effect" lists "0.000000" as both its minvalue and maxvalue, but non-zero values are used to specify what particle effect to attach.
 
**"'''<tt>description_string</tt>'''": The tokenized string that describes the attribute (eg. "<tt>#Attrib_RocketJumpDmgReduction</tt>" for the [[Gunboats]]' "rocket jump damage reduction" attribute, where "<tt>#Attrib_RocketJumpDmgReduction</tt>" is defined in tf_english.txt as "%s1% blast damage from rocket jumps"), or "''<tt>unused</tt>''" for hidden attributes that aren't listed (eg. a change in ammo count from the normal weapon)  If the language argument is specified the string for that language will be returned instead of the token.
 
**"'''<tt>description_format</tt>'''": A string describing how to format the value for a description:
 
***"''<tt>value_is_percentage</tt>''" for values that translate into percentages and are represented by that percentage (eg. changes to the blast radius)
 
***"''<tt>value_is_inverted_percentage</tt>''" for values that translate into percentages and are represented by the difference in that percentage from 100% (eg. changes to the fire rate)
 
***"''<tt>value_is_additive</tt>''" for values that are a specific number (eg. max health bonuses and bleed durations) and boolean attributes (such as [[The Sandman]]'s ability to knock out balls)
 
***"''<tt>value_is_additive_percentage</tt>''" for values that add to an existing percentage (e.g. The Ubersaw adding 25% charge every hit)
 
***"''<tt>value_is_date</tt>''" for values that are a unix timestamp
 
**"'''<tt>effect_type</tt>'''": "''<tt>positive</tt>''" if the effect is outright beneficial to the user (displayed in blue text in the item description window), "''<tt>negative</tt>''" if the effect is punitive to the user (red text), or "''<tt>neutral</tt>''" if the effect is more tangential to the normal behavior (eg. the [[Kritzkrieg]]'s ÜberCharge being critical hits rather than invulnerability) (white text).
 
  
=== Further notes ===
+
;ISteamApps: Methods relating to Steam Apps in general.
 +
:;[[WebAPI/GetAppList|GetAppList]]: Full list of every publicly facing program in the store/library.
 +
:;[[WebAPI/GetServersAtAddress|GetServersAtAddress]]: Shows all steam-compatible servers related to a IPv4 Address.
 +
:;[[WebAPI/UpToDateCheck|UpToDateCheck]]: Check if a given app version is the most current available.
  
The first 32 items listed describe the original class weapons, with an extraneous "TF_WEAPON_BUILDER" at defindex 28, which has the icon of the Engineer's Destroy PDA but the model of the Build PDA, and a "TF_WEAPON_FLAREGUN" at defindex 31, which uses "#TF_Weapon_Flaregun" for both item_name and item_type_name (where the normal "Unique Achievement Flaregun" uses "#TF_Unique_Achievement_Flaregun" for the item_name) and the pistol for the model. Every weapon in the first 32's name is its item_class in all caps. The next 3 items (defindex 32-35) describe abortive attempts at the original Medic unlockables, with the names being "Level 1 X" (where X is the name of the original item), and the original's art files defined (although the saw lists the Ubersaw's icon).
+
;ISteamEconomy: Methods relating to games' store's assets.
 +
:;[[WebAPI/GetAssetClassInfo|GetAssetClassInfo]]: Asset metadata
 +
:;[[WebAPI/GetAssetPrices|GetAssetPrices]]: Prices of items in the economy.
  
Both Engineer PDAs and the Spy PDA use "#TF_Weapon_PDA_Engineer" for both their item_type_name and their item_name.
+
;ISteamNews: Methods relating to Steam News.
 +
:;[[WebAPI/GetNewsForApp|GetNewsForApp]]: News feed for various games
  
You are welcome to use the backpack images provided by image_url and image_url_large directly or to copy the files to your own server.
+
;ISteamRemoteStorage: Methods relating to stored files.
 +
:;[[WebAPI/GetCollectionDetails|GetCollectionDetails]]:
 +
:;[[WebAPI/GetPublishedFileDetails|GetPublishedFileDetails]]:
 +
:;[[WebAPI/GetUGCFileDetails|GetUGCFileDetails]]: UGC file size, local filename, and URL.
  
== GetPlayerItems (v0001) ==
+
;ISteamUser: Methods relating to Steam users.
 +
:;[[WebAPI/GetFriendList|GetFriendList]]: User friend list
 +
:;[[WebAPI/GetPlayerBans|GetPlayerBans]]: Player ban/probation status
 +
:;[[WebAPI/GetPlayerSummaries|GetPlayerSummaries]]: User profile data
 +
:;[[WebAPI/GetUserGroupList|GetUserGroupList]]: Lists Group ID(s) linked with 64 bit ID
 +
:;[[WebAPI/ResolveVanityURL|ResolveVanityURL]]: Resolve vanity URL parts to a 64 bit ID.
  
The GetPlayerItems call returns a the items for a specific player.
+
;ISteamUserStats: Methods relating to User stats.
 +
:;[[WebAPI/GetGlobalAchievementPercentagesForApp|GetGlobalAchievementPercentagesForApp]]: Statistics showing how much of the player base have unlocked various achievements.
 +
:;[[WebAPI/GetGlobalStatsForGame|GetGlobalStatsForGame]]:
 +
:;[[WebAPI/GetNumberOfCurrentPlayers|GetNumberOfCurrentPlayers]]: Returns the current number of players for an app.
 +
:;[[WebAPI/GetPlayerAchievements|GetPlayerAchievements]]: Game achievements
 +
:;[[WebAPI/GetSchemaForGame|GetSchemaForGame]]:
 +
:;[[WebAPI/GetUserStatsForGame|GetUserStatsForGame]]:
  
The player is specified with their Steam ID number, as the "SteamID" value in the URL arguments. This is also known as a "SteamID64" value, which one can retrieve either through an OpenID transaction, or by going to the person's steam community page XML feed manually, such as http://steamcommunity.com/id/robinwalker?xml=1. The SteamID64 value is the value listed inside the <steamID64> tags (in the XML feed) and should be something like 76561197960435530.
+
;IPlayerService: Methods relating to a Steam user's games.
 +
:;[[WebAPI/GetRecentlyPlayedGames|GetRecentlyPlayedGames]]:
 +
:;[[WebAPI/GetOwnedGames|GetOwnedGames]]:
 +
:;[[WebAPI/GetSteamLevel|GetSteamLevel]]:
 +
:;[[WebAPI/GetBadges|GetBadges]]:
 +
:;[[WebAPI/GetCommunityBadgeProgress|GetCommunityBadgeProgress]]:
  
Example URL: http://api.steampowered.com/ITFItems_440/GetPlayerItems/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&SteamID=76561197960435530 (returns the items in Robin Walker's inventory)
+
;ISteamWebAPIUtil: Methods relating to the WebAPI itself.
 +
:;[[WebAPI/GetServerInfo|GetServerInfo]]: Returns WebAPI server time & checks server status.
 +
:;[[WebAPI/GetSupportedAPIList|GetSupportedAPIList]]: Lists all available WebAPI interfaces.
  
=== Status codes ===
+
=== Game specific interfaces ===
 +
==== Generic ====
 +
;IEconItems_<ID>: Methods relating to in-game items for supported games.
 +
:;[[WebAPI/GetPlayerItems|GetPlayerItems]]: Lists items in a player's backpack.
 +
:;[[WebAPI/GetSchema|GetSchema]]: Information about the items in a supporting game.
 +
:;[[WebAPI/GetSchemaURL|GetSchemaURL]]: Returns a URL for the games' item_game.txt file.
 +
:;[[WebAPI/GetStoreMetadata|GetStoreMetadata]]: Information about the game's store.
 +
:;[[WebAPI/GetStoreStatus|GetStoreStatus]]: The game's store status.
  
*'''<tt>1</tt>''': OK. Data returned as specified below.
+
;IGCVersion_<ID>: TODO.
*'''<tt>8</tt>''' ("<tt>SteamID parameter was missing</tt>"): The "steamID" parameter of the URL was not included, or if present was not a valid SteamID64 value.
+
:;[[WebAPI/GetClientVersion|GetClientVersion]]: TODO
*'''<tt>15</tt>''' ("<tt>Permission denied</tt>"): The player's profile is set to Private.
+
:;[[WebAPI/GetClusterVersion|GetClusterVersion]]: TODO
 +
:;[[WebAPI/GetServerVersion|GetServerVersion]]: TODO
  
=== Result layout ===
+
;ITFPromos_<ID>: TODO.
 +
:;[[WebAPI/GetItemID|GetItemID]]: TODO
 +
:;[[WebAPI/GrantItem|GrantItem]]: TODO
  
A list of the player's items is returned, as follows:
+
==== Dota 2 ====
 +
;IDOTA2Match_<ID>: Methods relating to Dota 2 matches.
 +
:;[[WebAPI/GetLeagueListing|GetLeagueListing]]: Information about DotaTV-supported leagues.
 +
:;[[WebAPI/GetLiveLeagueGames|GetLiveLeagueGames]]: A list of in-progress league matches, as well as details of that match as it unfolds.
 +
:;[[WebAPI/GetMatchDetails|GetMatchDetails]]: Information about a particular match.
 +
:;[[WebAPI/GetMatchHistory|GetMatchHistory]]: A list of matches, filterable by various parameters.
 +
:;[[WebAPI/GetMatchHistoryBySequenceNum|GetMatchHistoryBySequenceNum]]: A list of matches ordered by their sequence num.
 +
:;[[WebAPI/GetScheduledLeagueGames|GetScheduledLeagueGames]]: A list of scheduled league games coming up.
 +
:;[[WebAPI/GetTeamInfoByTeamID|GetTeamInfoByTeamID]]: A list of all the teams set up in-game.
 +
:;[[WebAPI/GetTournamentPlayerStats|GetTournamentPlayerStats]]: Stats about a particular player within a tournament.
 +
:;[[WebAPI/GetTopLiveGame|GetTopLiveGame]]: TODO
  
*"'''<tt>items</tt>'''": An object containing an unsorted array of "'''<tt>item</tt>'''":
+
;IEconDOTA2_<ID>: Methods relating to the Dota2 economy.
**"'''<tt>id</tt>'''": The unique ID of the specific item.
+
:;[[WebAPI/GetGameItems|GetGameItems]]: Dota 2 In-game items
**"'''<tt>defindex</tt>'''": the defindex of the item, as found in the item array returned from GetSchema.
+
:;[[WebAPI/GetItemIconPath|GetItemIconPath]]: TODO
**"'''<tt>level</tt>'''": The arbitrary "level" value of the item as displayed in the inventory.
+
:;[[WebAPI/GetHeroes|GetHeroes]]: A list of heroes within Dota 2.
**"'''<tt>quantity</tt>'''": 1.
+
:;[[WebAPI/GetRarities|GetRarities]]: Dota 2 item rarity list.
**"'''<tt>flag_achievement_granted</tt>'''": true if the item was unlocked by an [[Achievement]].
+
:;[[WebAPI/GetTournamentPrizePool|GetTournamentPrizePool]]: The current prizepool for specific tournaments.
**"'''<tt>flag_purchased</tt>'''": true if the item was purchased in the [[Mann Co. Store]].
+
:;[[WebAPI/GetEventStatsForAccount|GetEventStatsForAccount]]: TODO
**"'''<tt>flag_promotion</tt>'''": true if the item is promotional. (for example, the [[Lumbricus Lid]], [[Bill's Hat]], [[Max's Severed Head]], [[The Big Kill]], and [[The Lugermorph]])
 
**"'''<tt>inventory</tt>'''": An inventory token as described below, or 0 if the item has been awarded but not yet found (placed in the backpack).
 
**"'''<tt>quality</tt>'''": The "quality" of the item (see definition in GetSchema).
 
**"'''<tt>custom_name</tt>'''": The item's custom name if it has one.
 
**"'''<tt>attributes</tt>'''": If the item has additional effects to the ones normally associated with it as described in GetSchema, an object containing an array of "'''<tt>attribute</tt>'''":
 
***"'''<tt>defindex</tt>'''": (eg. 133 for the medal number attribute for the [[Gentle Manne's Service Medal]]).
 
***"'''<tt>value</tt>'''": The value for this attribute for this item (eg. the medal number for the [[Gentle Manne's Service Medal]]).
 
  
=== Inventory Token ===
+
;IDOTA2MatchStats_<ID>: TODO.
 +
:;[[WebAPI/GetRealtimeStats|GetRealtimeStats]]: TODO
  
The inventory token is a combination of class loadout flags and position in the player's backpack. This unsigned 32 bit number is split into two two-byte words. The high word contains flags for each class. A 1 bit in a class's slot indicates that the items is equipped in the appropriate loadout slot for that class. The low word contains the backback position with 0 being the upper left slot, 1 the second slot from the left on the top row, etc. Here it is visually:
+
;IDOTA2Fantasy_<ID>: Methods relating to the Dota 2 fantasy team system.
 +
:;[[WebAPI/GetFantasyPlayerStats|GetFantasyPlayerStats]]: TODO
 +
:;[[WebAPI/GetPlayerOfficialInfo|GetPlayerOfficialInfo]]: TODO
  
 +
;IDOTA2StreamSystem_<ID>: Methods relating to the Dota 2 streaming system.
 +
:;[[WebAPI/GetBroadcasterInfo|GetBroadcasterInfo]]: TODO
  
  ┌───────────────────────────────────────────────────────────────── Always 1
+
;IDOTA2Teams_<ID>: Methods relating to Dota 2 teams.
  │ ┌─┬─┬─┬─┬─┬─┬─────────────────────────────────────────────────── Unused
+
:;[[WebAPI/GetTeamInfo|GetTeamInfo]]: TODO
  │ │ │ │ │ │ │ │ ┌───────────────────────────────────────────────── Engineer
 
  │ │ │ │ │ │ │ │ │ ┌─────────────────────────────────────────────── Spy
 
  │ │ │ │ │ │ │ │ │ │ ┌───────────────────────────────────────────── Pyro
 
  │ │ │ │ │ │ │ │ │ │ │ ┌─────────────────────────────────────────── Heavy
 
  │ │ │ │ │ │ │ │ │ │ │ │ ┌───────────────────────────────────────── Medic
 
  │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────────────────────────────── Demoman
 
  │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌───────────────────────────────────── Soldier
 
  │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────────────────────────── Sniper
 
  │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌───────────────────────────────── Scout
 
  │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─ Backpack Position
 
  │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
 
  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 
  
Examples:
+
;IDOTA2AutomatedTourney_<ID>: TODO
  1 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1  Equipped Pyro item
+
:;[[WebAPI/GetActiveTournamentList|GetActiveTournamentList]]: TODO
                                                                      in backback slot 9
 
  1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 1  Unequipped item
 
                                                                      in backback slot 41
 
  1 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 1 0  Equipped by Pyro and Engy
 
                                                                      in backback slot 42
 
  
In C++ the backpack position and equip status could be determined from an inventory token with these functions:
+
;IDOTA2Ticket_<ID>: TODO
 +
:;[[WebAPI/SetSteamAccountPurchased|SetSteamAccountPurchased]]: TODO
 +
:;[[WebAPI/SteamAccountValidForEvent|SteamAccountValidForEvent]]: TODO
  
#define CLASS_SCOUT    0
+
==== Portal 2 ====
#define CLASS_SNIPER    1
+
;IPortal2Leaderboards_<ID>: Methods relating to Portal 2 Leaderboards.
#define CLASS_SOLDIER  2
+
:;[[WebAPI/GetBucketizedData|GetBucketizedData]]: TODO
#define CLASS_DEMOMAN  3
 
#define CLASS_MEDIC    4
 
#define CLASS_HEAVY    5
 
#define CLASS_PYRO      6
 
#define CLASS_SPY      7
 
#define CLASS_ENGINEER  8
 
 
uint32 ExtractBackpackPosition( uint32 unInventoryToken )
 
{
 
  return unInventoryToken & 0xFFFF;
 
}
 
 
bool IsEquippedForClass( uint32 unInventoryToken, uint32 unClass )
 
{
 
  return 0 != unInventoryToken & ( 1 << ( unClass + 16 ) );
 
}
 
  
Similarly, in PHP (assuming $class is a numeric matching the defines above):
+
=== Other undocumented interfaces ===
 +
;ISteamGameServerAccount: TODO
 +
;ISteamOAuth2: TODO
 +
;ISteamUserAuth: TODO
 +
;ISteamWebUserPresenceOAuth: TODO
  
function is_equipped_for_class($class,$inventory_token)
+
== Notes ==
{
 
  return ($inventory_token & 0x80000000) && ($inventory_token & (0x00010000 << $class));
 
}
 
function extract_backpack_position($inventory_token)
 
{
 
  return $inventory_token & 0x0000FFFF;
 
}
 
  
In Lua 5.1 (which does not have bitwise operators), these functions can be used:
+
=== List of IDs ===
  
function extract_backpack_position(inventory_token)
+
{{anchor|appids}}
  return inventory_token % 2^16
+
''For a complete list, see [[WebAPI/GetAppList|GetAppList]].''
end
+
;240: Counter-Strike: Source
+
;260: Counter-Strike: Source Beta
function is_equipped_for_class(inventory_token, class)
+
;440: Team Fortress 2
  return inventory_token % 2^(class+17) >= 2^(class+16)
+
;520: Team Fortress 2 Beta
end
+
;570: Dota 2
 +
;620: Portal 2
 +
;710: Counter-Strike: Global Offensive Beta Dev
 +
;730: Counter-Strike: Global Offensive
 +
;816: Dota 2 Private Beta
 +
;841: Portal 2 Beta
 +
;205790: Dota 2 (Beta) Test
  
== GetGoldenWrenches (v0001) ==
+
=== Methods Requiring a 64-bit User ID ===
 
+
Most API requests that take an ID parameter require a 64 bit ID, if one is not readily available a vanity URL part can be resolved via [[WebAPI/ResolveVanityURL|ResolveVanityURL]].
The GetGoldenWrenches call returns the entire list of Golden Wrench weapons granted as part of the Engineer Update.
 
 
 
Example URL: http://api.steampowered.com/ITFItems_440/GetGoldenWrenches/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
 
 
=== Arguments ===
 
 
 
None
 
 
 
=== Return Value ===
 
 
 
Returns the list of golden wrenches:
 
 
 
*"'''<tt>results</tt>'''"
 
**"'''<tt>wrenches</tt>'''": Contains a single child 'wrench' that is an unsorted list of Golden Wrenches
 
***"'''<tt>steamID</tt>'''": 64-bit Steam ID of the owner of the wrench. Profile details for that user can be retrieved with ISteamUser/GetPlayerSummaries. [http://developer.valvesoftware.com/wiki/Steam_Web_API#GetPlayerSummaries_.28v0001.29]
 
***"'''<tt>timestamp</tt>'''": Seconds since 1/1/1970 of the time the wrench was crafted
 
***"'''<tt>itemID</tt>'''": ItemID of the wrench. This will match the itemID returned by GetPlayerItems for this user.
 
***"'''<tt>wrenchNumber</tt>'''": The serial number on the wrench. This will match the serial number attribute on the item itself.
 
  
 
== Implementations ==
 
== Implementations ==
 
+
<!-- Please only add notable implementations to this section. If you have another one to add put it in the Implementations subpage. -->
* [http://developer.valvesoftware.com/wiki/Steam_Condenser Steam Condenser] Ruby, PHP, and Java library.
+
* [https://github.com/koraktor/steam-condenser Steam Condenser] Ruby, PHP, and Java library.
* [http://github.com/swixel/tf2webappy TF2 Web APpy] A small Python class.
+
* [https://github.com/Lagg/steamodd Steamodd] Python library, used by OPTF2.
* [http://gitorious.org/steamodd/main Steamodd] Python module
+
* [[WebAPI/Implementations|More]]
** [http://agg.havoc.ift.uni.wroc.pl/tf2/pack/ OPTF2] online viewer ([http://gitorious.org/steamodd/optf2 code])
 
** [http://gitorious.org/steamodd/optf2tty OPTF2tty] - Simple text viewer, colored output in supporting terminals.
 
  
 
== See also ==
 
== See also ==
  
* [[WebAPI/Feedback]] for requests / suggestions / issues.
+
* [[Talk:WebAPI/Feedback|Feedback]] for requests, suggestions, and issues.
* [http://developer.valvesoftware.com/wiki/Steam_Web_API Steam Web API] for more information and other methods.
 
  
 
[[Category:Valve]]
 
[[Category:Valve]]
 +
[[Category:WebAPI| ]]

Latest revision as of 19:40, 3 June 2023

Contributing

If you would like to help in writing API documentation there is a tool available here (requires python) that can generate skeleton documentation pages that match the style guidelines and can be easily copied and pasted.

Otherwise be sure to follow the existing structure and format of the documentation to keep things consistent.

Common elements

Parameters

Most WebAPI methods take the following arguments in their URL:

key
Your Steam Web API key. Without this, the server will return an HTTP 403 (forbidden) error. A key can be generated here.
format (Optional)
The file format to return output in.
json (default)
The JavaScript Object Notation format
xml
Standard XML
vdf
Valve Data Format
language (Optional)
The ISO639-1 language code for the language all tokenized strings should be returned in. Not all strings have been translated to every language. If a language does not have a string, the English string will be returned instead. If this parameter is omitted the string token will be returned for the strings.

Terminology

A "tokenized string" refers to a string containing "#"-prefixed tokens that are replaced with the equivalent string in the game's VDF for the chosen language. For instance, "TF_Weapon_Jar" is defined as "Jar Based Karate" in tf/resource/tf_english.txt (as found in "team fortress 2 content.gcf").

Methods

General interfaces

ISteamApps
Methods relating to Steam Apps in general.
GetAppList
Full list of every publicly facing program in the store/library.
GetServersAtAddress
Shows all steam-compatible servers related to a IPv4 Address.
UpToDateCheck
Check if a given app version is the most current available.
ISteamEconomy
Methods relating to games' store's assets.
GetAssetClassInfo
Asset metadata
GetAssetPrices
Prices of items in the economy.
ISteamNews
Methods relating to Steam News.
GetNewsForApp
News feed for various games
ISteamRemoteStorage
Methods relating to stored files.
GetCollectionDetails
GetPublishedFileDetails
GetUGCFileDetails
UGC file size, local filename, and URL.
ISteamUser
Methods relating to Steam users.
GetFriendList
User friend list
GetPlayerBans
Player ban/probation status
GetPlayerSummaries
User profile data
GetUserGroupList
Lists Group ID(s) linked with 64 bit ID
ResolveVanityURL
Resolve vanity URL parts to a 64 bit ID.
ISteamUserStats
Methods relating to User stats.
GetGlobalAchievementPercentagesForApp
Statistics showing how much of the player base have unlocked various achievements.
GetGlobalStatsForGame
GetNumberOfCurrentPlayers
Returns the current number of players for an app.
GetPlayerAchievements
Game achievements
GetSchemaForGame
GetUserStatsForGame
IPlayerService
Methods relating to a Steam user's games.
GetRecentlyPlayedGames
GetOwnedGames
GetSteamLevel
GetBadges
GetCommunityBadgeProgress
ISteamWebAPIUtil
Methods relating to the WebAPI itself.
GetServerInfo
Returns WebAPI server time & checks server status.
GetSupportedAPIList
Lists all available WebAPI interfaces.

Game specific interfaces

Generic

IEconItems_<ID>
Methods relating to in-game items for supported games.
GetPlayerItems
Lists items in a player's backpack.
GetSchema
Information about the items in a supporting game.
GetSchemaURL
Returns a URL for the games' item_game.txt file.
GetStoreMetadata
Information about the game's store.
GetStoreStatus
The game's store status.
IGCVersion_<ID>
TODO.
GetClientVersion
TODO
GetClusterVersion
TODO
GetServerVersion
TODO
ITFPromos_<ID>
TODO.
GetItemID
TODO
GrantItem
TODO

Dota 2

IDOTA2Match_<ID>
Methods relating to Dota 2 matches.
GetLeagueListing
Information about DotaTV-supported leagues.
GetLiveLeagueGames
A list of in-progress league matches, as well as details of that match as it unfolds.
GetMatchDetails
Information about a particular match.
GetMatchHistory
A list of matches, filterable by various parameters.
GetMatchHistoryBySequenceNum
A list of matches ordered by their sequence num.
GetScheduledLeagueGames
A list of scheduled league games coming up.
GetTeamInfoByTeamID
A list of all the teams set up in-game.
GetTournamentPlayerStats
Stats about a particular player within a tournament.
GetTopLiveGame
TODO
IEconDOTA2_<ID>
Methods relating to the Dota2 economy.
GetGameItems
Dota 2 In-game items
GetItemIconPath
TODO
GetHeroes
A list of heroes within Dota 2.
GetRarities
Dota 2 item rarity list.
GetTournamentPrizePool
The current prizepool for specific tournaments.
GetEventStatsForAccount
TODO
IDOTA2MatchStats_<ID>
TODO.
GetRealtimeStats
TODO
IDOTA2Fantasy_<ID>
Methods relating to the Dota 2 fantasy team system.
GetFantasyPlayerStats
TODO
GetPlayerOfficialInfo
TODO
IDOTA2StreamSystem_<ID>
Methods relating to the Dota 2 streaming system.
GetBroadcasterInfo
TODO
IDOTA2Teams_<ID>
Methods relating to Dota 2 teams.
GetTeamInfo
TODO
IDOTA2AutomatedTourney_<ID>
TODO
GetActiveTournamentList
TODO
IDOTA2Ticket_<ID>
TODO
SetSteamAccountPurchased
TODO
SteamAccountValidForEvent
TODO

Portal 2

IPortal2Leaderboards_<ID>
Methods relating to Portal 2 Leaderboards.
GetBucketizedData
TODO

Other undocumented interfaces

ISteamGameServerAccount
TODO
ISteamOAuth2
TODO
ISteamUserAuth
TODO
ISteamWebUserPresenceOAuth
TODO

Notes

List of IDs

For a complete list, see GetAppList.

240
Counter-Strike: Source
260
Counter-Strike: Source Beta
440
Team Fortress 2
520
Team Fortress 2 Beta
570
Dota 2
620
Portal 2
710
Counter-Strike: Global Offensive Beta Dev
730
Counter-Strike: Global Offensive
816
Dota 2 Private Beta
841
Portal 2 Beta
205790
Dota 2 (Beta) Test

Methods Requiring a 64-bit User ID

Most API requests that take an ID parameter require a 64 bit ID, if one is not readily available a vanity URL part can be resolved via ResolveVanityURL.

Implementations

See also

  • Feedback for requests, suggestions, and issues.