WebAPI

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.

This page documents the web API calls that allow you to retrieve information from the item system in Team Fortress 2.

Calls to the TF2 Web API require a valid Steam Web API key to function. You can get your own API Key here. Each example URL will only work after replacing "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" with your API key.

Common arguments

All TF2 methods take the following arguments:

• key: Your Steam Web API key. Without this, the server will return a 403 Forbidden HTTP status.
• format (optional): The format to return the data in ("json" for JSON, "xml" for XML, or "vdf" for VDF). The structure of the data for each format is described at

http://developer.valvesoftware.com/wiki/Steam_Web_API#Formats. If no format is specified, the data will be returned with the default of JSON.

Common result structure

All TF2 methods return a "result" object containing a status code (at "status") and either the data requested or a status message explaining why the data was not returned (at "statusDetail").

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

Status codes

• 1: The normal code. Should always be returned.

Result data

• "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" value (see below)
    • "class": The attribute's "attribute_class" value (see below)
    • "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)
  • "defindex":
  • "attribute_class":
  • "minvalue":
  • "maxvalue":
  • "description_string":
  • "description_format":
  • "effect_type": "positive" if the effect is outright beneficial to the user (displayed in blue text in the item description window), "negative" if the effect is punitive to the user (red text), or "neutral" if the effect is more tangential to the normal behavior (eg. the Kritzkrieg's ubercharge being critical hits rather than invulnerability) (white text).

Further information

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 a specific player.

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.

Example URL: http://api.steampowered.com/ITFItems_440/GetPlayerItems/v0001/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&SteamID=76561197960435530 (returns the items in Robin Walker's inventory)

Status codes

• 1: OK. Data returned as specified below.
• 8 ("SteamID parameter was missing"): The "steamID" parameter of the URL was not included, or if present was not a valid SteamID64 value.
• 15 ("Permission denied"): The player's profile is set to Private.

Result layout

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 
                          } 
                      ] 
                  } 
              }, 
          ] 
      }
  } 
}

Inventory Token

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:

  ┌───────────────────────────────────────────────────────────────── Always 1
  │ ┌─┬─┬─┬─┬─┬─┬─────────────────────────────────────────────────── Unused
  │ │ │ │ │ │ │ │ ┌───────────────────────────────────────────────── 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:

  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 
                                                                     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:

#define CLASS_SCOUT     0
#define CLASS_SNIPER    1
#define CLASS_SOLDIER   2
#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)

function is_equipped_for_class($class,$inventory_token)
{
	return ($inventory_token & 0x80000000) && ($inventory_token & (0x00010000 << $class)); 
}
function extract_backpack_position($inventory_token)
{
	return $inventory_token & 0x0000FF;
}