Difference between revisions of "WebAPI"

From Team Fortress Wiki
Jump to: navigation, search
(Return Value)
(brb, committing)
Line 1: Line 1:
The '''WebAPI''' 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].<br>
+
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.
  
 
== Format differences ==
 
== Format differences ==
Line 8: Line 8:
 
** The API contains an object containing an object named "result".
 
** 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).
 
** 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'''
 
** XML Attributes are not used.
 
** XML Attributes are not used.
 
** Arrays are represented as a series of sub-elements in the containing element of the type of the array.
 
** 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)''
 
*'''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).
 
** 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).
Line 17: Line 19:
 
*** 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.
 
*** 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.
 
** 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.
  
== GetSchema (v0001) ==
+
If no format is specified, the API will default to JSON.
  
Example URL: http://api.steampowered.com/ITFItems_440/GetSchema/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
== Methods ==
  
=== Arguments ===
+
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].
  
None
+
=== GetSchema (v0001) ===
  
=== Return Value ===
+
This method returns the item schema for the current build of Team Fortress 2. It takes no additional parameters.
  
Returns the item schema for the current build of Team Fortress 2, structured as follows:  
+
Example URL: http://api.steampowered.com/ITFItems_440/GetSchema/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&format=json
  
  {
+
==== Return data layout ====
  "result":  
+
   
  {
+
*'''"result"''': An object containing the results of the call.
      "status": 1,
+
**'''"status"''': A numeric status code of unknown meaning.
      "qualities":  
+
**'''"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.
          "normal": 0,
+
***'''"common"''' ''(1)'': No weapons have this listed as their quality.
          "common": 1,
+
***'''"rare"''' ''(2)'': No weapons have this listed as their quality.
          "rare": 2,
+
***'''"unique"''' ''(3)'': All other items have this listed as their quality.
          "unique": 3,
+
***'''"community"''' ''(7)'': No weapons have this as listed their quality.
          "community": 7,
+
***'''"developer"''' ''(8)'': No weapons have this as listed their quality.
          "developer": 8,
+
***'''"selfmade"''' ''(9)'': No weapons have this as listed their quality.
          "selfmade": 9
+
**'''"items"''': An object containing an array of '''"item"''':
      },
+
***'''"name"''': A string describing the item (eg. "Unique Achievement Feign Watch" for the [[Dead Ringer]]).
      "items":  
+
***'''"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":  
+
***'''"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"'''
                  "name": "TF_WEAPON_BAT",
+
***'''"item_quality"'''
                  "defindex": 0,
+
***'''"image_inventory"''':
                  "item_class": "tf_weapon_bat",
+
***'''"model_player"''': The model to display for the item, or null if the object has no model.
                  "item_type_name": "#TF_Weapon_Bat",
+
***'''"attributes"''' ''(Optional)'': If the item has gameplay effects, an object containing an array of '''"attribute"''':
                  "item_name": "#TF_Weapon_Bat",
+
****'''"name"''': The attribute's "name" ''(see below)''
                  "item_slot": "melee",
+
****'''"class"''':
                  "item_quality": 0,
+
****'''"value"''':
                  "image_inventory": "backpack\/weapons\/c_models\/c_bat",
+
**'''"attributes"''': An object containing an array of '''"attribute"''':
                  "model_player": "models\/weapons\/w_models\/w_bat.mdl"
+
***'''"name"''': A name describing the attribute (eg. "scattergun has knockback" for the [[Force-A-Nature]]'s knockback)
              },
+
***
          ]
+
***
      },
+
***
      "attributes":  
+
***
      {
+
***
          "attribute":  
+
***
          [
+
***
              {
 
                  "name": "damage penalty",
 
                  "defindex": 1,
 
                  "attribute_class": "mult_dmg",
 
                  "min_value": 0.950000,
 
                  "max_value": 0.850000,
 
                  "description_string": "#Attrib_DamageDone_Negative",
 
                  "description_format": "value_is_percentage",
 
                  "effect_type": "negative"
 
              },
 
          ]
 
      }
 
  }
 
}
 
  
 +
==== Return data implementation ====
  
 
+
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).
The defindex fields in items and attributes corresponds with the same field in the GetPlayerItems calls.
 
  
 
== GetPlayerItems (v0001) ==
 
== GetPlayerItems (v0001) ==

Revision as of 11:13, 2 July 2010

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.

Format differences

Every method can return its results in 3 different formats: JSON, XML, and VDF. Each format represents the data described herein differently:

  • JSON
    • 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.

Methods

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 here.

GetSchema (v0001)

This method returns the item schema for the current build of Team Fortress 2. It takes no additional parameters.

Example URL: http://api.steampowered.com/ITFItems_440/GetSchema/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&format=json

Return data layout

  • "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

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).

GetPlayerItems (v0001)

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.

Example URL: http://api.steampowered.com/ITFItems_440/GetPlayerItems/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&steamID=12345678

Arguments

SteamID

Return Value

A list of the player's items is returned, as follows:

{ 
  "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.