Difference between revisions of "WebAPI"

From Team Fortress Wiki
Jump to: navigation, search
(brb, committing)
m
 
(180 intermediate revisions by 35 users not shown)
Line 1: Line 1:
−
The Steam Web API is documented at http://steamcommunity.com/dev. Where the Steam Web API ends and the TF2 Web API begins is not yet defined (the latter currently comprising the whole of the former), so this page documents everything not listed there.
+
== Contributing ==
  
−
== Format differences ==
+
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.
  
−
Every method can return its results in 3 different formats: JSON, XML, and VDF. Each format represents the data described herein differently:
+
Otherwise be sure to follow the existing structure and format of the documentation to keep things consistent.
  
−
*'''JSON'''
+
== Common elements ==
−
** The API contains an object containing an object named "result".
 
−
** Arrays are represented as an array with the name of the type of the objects in the array (ie. an object named "items" containing an array of objects of type "item" would be represented as an object named "items" containing an array named "item" containing several objects following the "item" structure).
 
−
** Null is represented as JSON's null.
 
−
*'''XML'''
 
−
** XML Attributes are not used.
 
−
** Arrays are represented as a series of sub-elements in the containing element of the type of the array.
 
−
** Null is represented by the word "null" between the element's tags.
 
−
*'''VDF''' ''(Valve Data Format)''
 
−
** This is Valve's internal data format, seen in TF2's "scripts" folder (available in "team fortress 2 client content.gcf"). GetSchema returns data similar to "items/items_game.txt" (although qualities are not expanded into objects with a "value" field).
 
−
** It appears to be undocumented, but it works similarly to JSON's objects:
 
−
*** A member is represented by a quoted string, followed by a newline and an open brace.
 
−
*** A value is represented as a key-value pair of quoted strings on the same line separated by a tab character. Each sub-object is indented by one tab character.
 
−
** Arrays in the data are represented as a VDF array with the name of the type of the objects in the array, with a VDF array being an object with each item being prefixed with its numeric key as a quoted string.
 
−
** Null is represented as an empty string.
 
  
−
If no format is specified, the API will default to JSON.
+
=== 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 [http://www.steamcommunity.com/dev/apikey here].
 +
;{{API optional|format}}: The file format to return output in.
 +
:;<code>json</code> (default): The [https://www.json.org/json-en.html JavaScript Object Notation] format
 +
:;<code>xml</code>: Standard XML
 +
:;<code>vdf</code>: [[WebAPI/VDF|Valve Data Format]]
 +
;{{API optional|language}}
 +
: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 ===
 +
 
 +
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").
  
 
== Methods ==
 
== Methods ==
 +
=== General interfaces ===
 +
 +
;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.
 +
 +
;ISteamEconomy: Methods relating to games' store's assets.
 +
:;[[WebAPI/GetAssetClassInfo|GetAssetClassInfo]]: Asset metadata
 +
:;[[WebAPI/GetAssetPrices|GetAssetPrices]]: Prices of items in the economy.
 +
 +
;ISteamNews: Methods relating to Steam News.
 +
:;[[WebAPI/GetNewsForApp|GetNewsForApp]]: News feed for various games
 +
 +
;ISteamRemoteStorage: Methods relating to stored files.
 +
:;[[WebAPI/GetCollectionDetails|GetCollectionDetails]]:
 +
:;[[WebAPI/GetPublishedFileDetails|GetPublishedFileDetails]]:
 +
:;[[WebAPI/GetUGCFileDetails|GetUGCFileDetails]]: UGC file size, local filename, and URL.
 +
 +
;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.
 +
 +
;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]]:
 +
 +
;IPlayerService: Methods relating to a Steam user's games.
 +
:;[[WebAPI/GetRecentlyPlayedGames|GetRecentlyPlayedGames]]:
 +
:;[[WebAPI/GetOwnedGames|GetOwnedGames]]:
 +
:;[[WebAPI/GetSteamLevel|GetSteamLevel]]:
 +
:;[[WebAPI/GetBadges|GetBadges]]:
 +
:;[[WebAPI/GetCommunityBadgeProgress|GetCommunityBadgeProgress]]:
 +
 +
;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.
 +
 +
=== 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.
 +
 +
;IGCVersion_<ID>: TODO.
 +
:;[[WebAPI/GetClientVersion|GetClientVersion]]: TODO
 +
:;[[WebAPI/GetClusterVersion|GetClusterVersion]]: TODO
 +
:;[[WebAPI/GetServerVersion|GetServerVersion]]: TODO
 +
 +
;ITFPromos_<ID>: TODO.
 +
:;[[WebAPI/GetItemID|GetItemID]]: TODO
 +
:;[[WebAPI/GrantItem|GrantItem]]: TODO
 +
 +
==== 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
 +
 +
;IEconDOTA2_<ID>: Methods relating to the Dota2 economy.
 +
:;[[WebAPI/GetGameItems|GetGameItems]]: Dota 2 In-game items
 +
:;[[WebAPI/GetItemIconPath|GetItemIconPath]]: TODO
 +
:;[[WebAPI/GetHeroes|GetHeroes]]: A list of heroes within Dota 2.
 +
:;[[WebAPI/GetRarities|GetRarities]]: Dota 2 item rarity list.
 +
:;[[WebAPI/GetTournamentPrizePool|GetTournamentPrizePool]]: The current prizepool for specific tournaments.
 +
:;[[WebAPI/GetEventStatsForAccount|GetEventStatsForAccount]]: TODO
  
−
The following web API calls allow you to retrieve information from the item system in Team Fortress 2. Each call requires a valid API Key to function. You can get your own API Key [http://www.steamcommunity.com/dev/apikey here].
+
;IDOTA2MatchStats_<ID>: TODO.
 +
:;[[WebAPI/GetRealtimeStats|GetRealtimeStats]]: TODO
  
−
=== GetSchema (v0001) ===
+
;IDOTA2Fantasy_<ID>: Methods relating to the Dota 2 fantasy team system.
 +
:;[[WebAPI/GetFantasyPlayerStats|GetFantasyPlayerStats]]: TODO
 +
:;[[WebAPI/GetPlayerOfficialInfo|GetPlayerOfficialInfo]]: TODO
  
−
This method returns the item schema for the current build of Team Fortress 2. It takes no additional parameters.
+
;IDOTA2StreamSystem_<ID>: Methods relating to the Dota 2 streaming system.
 +
:;[[WebAPI/GetBroadcasterInfo|GetBroadcasterInfo]]: TODO
  
−
Example URL: http://api.steampowered.com/ITFItems_440/GetSchema/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&format=json
+
;IDOTA2Teams_<ID>: Methods relating to Dota 2 teams.
 +
:;[[WebAPI/GetTeamInfo|GetTeamInfo]]: TODO
  
−
==== Return data layout ====
+
;IDOTA2AutomatedTourney_<ID>: TODO
−
+
:;[[WebAPI/GetActiveTournamentList|GetActiveTournamentList]]: TODO
−
*'''"result"''': An object containing the results of the call.
 
−
**'''"status"''': A numeric status code of unknown meaning.
 
−
**'''"qualities"''': 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):
 
−
***'''"normal"''' ''(0)'': All of the standard inherent basic class weapons have this listed as their quality.
 
−
***'''"common"''' ''(1)'': No weapons have this listed as their quality.
 
−
***'''"rare"''' ''(2)'': No weapons have this listed as their quality.
 
−
***'''"unique"''' ''(3)'': All other items have this listed as their quality.
 
−
***'''"community"''' ''(7)'': No weapons have this as listed their quality.
 
−
***'''"developer"''' ''(8)'': No weapons have this as listed their quality.
 
−
***'''"selfmade"''' ''(9)'': No weapons have this as listed their quality.
 
−
**'''"items"''': An object containing an array of '''"item"''':
 
−
***'''"name"''': A string describing the item (eg. "Unique Achievement Feign Watch" for the [[Dead Ringer]]).
 
−
***'''"defindex"''': The item's unique index as seen in GetPlayerItems.
 
−
***'''"item_class"''': The item's class in game (ie. what you would use as the argument to "equip" in the console to equip it).
 
−
***'''"item_type_name"''': The string containing pound-prefixed tokens for the string in TF2's language files that describes the item's class (ie. "#TF_Wearable_Shield" for the [[Chargin' Targe]]).
 
−
***'''"item_name"'''
 
−
***'''"item_slot"'''
 
−
***'''"item_quality"'''
 
−
***'''"image_inventory"''':
 
−
***'''"model_player"''': The model to display for the item, or null if the object has no model.
 
−
***'''"attributes"''' ''(Optional)'': If the item has gameplay effects, an object containing an array of '''"attribute"''':
 
−
****'''"name"''': The attribute's "name" ''(see below)''
 
−
****'''"class"''':
 
−
****'''"value"''':
 
−
**'''"attributes"''': An object containing an array of '''"attribute"''':
 
−
***'''"name"''': A name describing the attribute (eg. "scattergun has knockback" for the [[Force-A-Nature]]'s knockback)
 
−
***
 
−
***
 
−
***
 
−
***
 
−
***
 
−
***
 
−
***
 
  
−
==== Return data implementation ====
+
;IDOTA2Ticket_<ID>: TODO
 +
:;[[WebAPI/SetSteamAccountPurchased|SetSteamAccountPurchased]]: TODO
 +
:;[[WebAPI/SteamAccountValidForEvent|SteamAccountValidForEvent]]: TODO
  
−
The first 32 items listed describe the original class weapons, with the name being the symbolic token for that weapon. The next 3 (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).
+
==== Portal 2 ====
 +
;IPortal2Leaderboards_<ID>: Methods relating to Portal 2 Leaderboards.
 +
:;[[WebAPI/GetBucketizedData|GetBucketizedData]]: TODO
  
−
== GetPlayerItems (v0001) ==
+
=== Other undocumented interfaces ===
 +
;ISteamGameServerAccount: TODO
 +
;ISteamOAuth2: TODO
 +
;ISteamUserAuth: TODO
 +
;ISteamWebUserPresenceOAuth: TODO
  
−
The GetPlayerItems call returns a the items for the player specified. If a player has their Steam community profile set to Private you will not be able to retrieve their items.
+
== Notes ==
  
−
Example URL: http://api.steampowered.com/ITFItems_440/GetPlayerItems/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&steamID=12345678
+
=== List of IDs ===
  
−
=== Arguments ===
+
{{anchor|appids}}
 +
''For a complete list, see [[WebAPI/GetAppList|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
  
−
'''SteamID'''
+
=== 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]].
  
−
=== Return Value ===
+
== Implementations ==
 +
<!-- Please only add notable implementations to this section. If you have another one to add put it in the Implementations subpage. -->
 +
* [https://github.com/koraktor/steam-condenser Steam Condenser] Ruby, PHP, and Java library.
 +
* [https://github.com/Lagg/steamodd Steamodd] Python library, used by OPTF2.
 +
* [[WebAPI/Implementations|More]]
  
−
A list of the player's items is returned, as follows:
+
== See also ==
  
−
{
+
* [[Talk:WebAPI/Feedback|Feedback]] for requests, suggestions, and issues.
−
  "result": {
 
−
      "status": 1,
 
−
      "items": {
 
−
          "item": [  
 
−
              {
 
−
                  "id": 827,
 
−
                  "defindex": 166,
 
−
                  "level": 5,
 
−
                  "quality": 3,
 
−
                  "inventory": 2147483650,  
 
−
                  "quantity": 1,  
 
−
                  "attributes":
 
−
                  {
 
−
                      "attribute": [
 
−
                          {
 
−
                              "defindex": 143,
 
−
                              "value": 1272326400.000000
 
−
                          }
 
−
                      ]
 
−
                  }
 
−
              },
 
−
          ]
 
−
      }
 
−
  }
 
−
}
 
  
−
If a player's profile is set to Private the status field will be set to 15 (Access Denied) and there will be no items field.
+
[[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.
Retrieved from "https://wiki.teamfortress.com/w/index.php?title=WebAPI&oldid=3433920"