WebAPI

From Team Fortress Wiki
Revision as of 17:42, 5 July 2010 by Joe (talk | contribs) (Made this new API match the others)
Jump to: navigation, search

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 elements

Arguments

All TF2 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.
  • 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.

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

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

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 ISO639-1[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

  • 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): In the list of items returned by GetSchema, all of the standard inherent basic class weapons have this listed as their quality.
    • "common" (1): In the list of items returned by GetSchema, no items have this listed as their quality.
    • "rare" (2): In the list of items returned by GetSchema, no items have this listed as their quality.
    • "unique" (3): 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.
    • "community" (7): 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.
    • "developer" (8): 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.
    • "selfmade" (9): 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.
  • "qualityNames": 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.
  • "items": An object containing an array of "item":
    • "name": A string that defines the item in the items_game.txt
    • "defindex": The item's unique index, used to refer to instances of the item 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 tokenized string that describes the item's class (eg. "#TF_Wearable_Shield" 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.
    • "item_name": The tokenized string for the item's name (eg. "#TF_Spy_Camera_Beard" for the Camera Beard). If the language argument is specified the string for that language will be returned instead of the token.
    • "item_slot": A string describing what loadout slot the item corresponds to:
      • "primary" for primary slot items (including "Slot Token - Primary")
      • "secondary" for secondary slot items (including "Slot Token - Secondary")
      • "melee" for melee slot items (including "Slot Token - Melee")
      • "head" for hats and "Slot Token - Head"
      • "misc" for misc slot items such as medals
      • "pda" for the Engineer's Build PDA, the Spy's Disguise Kit, and "Slot Token - PDA"
      • "pda2" for the Engineer's Destroy PDA, the Spy's Invisibility Watch, the Cloak and Dagger, the Dead Ringer, and "Slot Token - PDA2"
      • "Engineer" for metal and class tokens (yes, all class tokens)
      • "building" for "TF_WEAPON_BUILDER" (an unused copy of the Engineer's Build PDA) and the unused "Slot Token - Building"
      • "grenade" for only the unused "Slot Token - Grenade"
    • "item_quality": The item's normal quality value. See description of "qualities" above.
    • "image_inventory": The image to display, as an escaped-slash ("\/") path to the material, without the extension
    • "model_player": 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.
    • "attributes" (Optional): If the item has effects normally associated with it, 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": 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)
  • "attributes": An object containing an array of "attribute":
    • "name": A name describing the attribute (eg. "damage bonus" for damage increases found on weapons such as the Scotsman's Skullcutter, or "scattergun has knockback" for the Force-A-Nature's knockback)
    • "defindex": The attribute's unique index, possibly used to refer to unique instances of the item with these attributes in GetPlayerItems.
    • "attribute_class": an underscore-based name for the attribute (eg. "mult_dmg" for the attribute whose name is "damage bonus")
    • "minvalue": The minimum value allowed for this attribute.
    • "maxvalue": 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.
    • "description_string": The tokenized string that describes the attribute (eg. "#Attrib_RocketJumpDmgReduction" for the Gunboats' "rocket jump damage reduction" attribute, where "#Attrib_RocketJumpDmgReduction" is defined in tf_english.txt as "%s1% blast damage from rocket jumps"), or "unused" 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.
    • "description_format": A string describing how to format the value for a description:
      • "value_is_percentage" for values that translate into percentages and are represented by that percentage (eg. changes to the blast radius)
      • "value_is_inverted_percentage" for values that translate into percentages and are represented by the difference in that percentage from 100% (eg. changes to the fire rate)
      • "value_is_additive" 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)
    • "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 notes

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

Both Engineer PDAs and the Spy PDA use "#TF_Weapon_PDA_Engineer" for both their item_type_name and their item_name.

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:

  • "items": An object containing an unsorted array of "item":
    • "id": The unique ID of the specific item.
    • "defindex": the defindex of the item, as found in the item array returned from GetSchema.
    • "level": The arbitrary "level" value of the item as displayed in the inventory.
    • "quantity": 1.
    • "inventory": An inventory token as described below, or 0 if the item has been awarded but not yet found (placed in the backpack).
    • "quality": The "quality" of the item (see definition in GetSchema).
    • "attributes": If the item has additional effects to the ones normally associated with it as described in GetSchema, an object containing an array of "attribute":

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 & 0x0000FFFF;
}

In Lua 5.1 (which does not have bitwise operators), these functions can be used: 

function extract_backpack_position(inventory_token)
  return inventory_token % 2^16
end

function is_equipped_for_class(inventory_token, class)
  return inventory_token % 2^(class+17) >= 2^(class+16)
end

GetGoldenWrenches (v0001)

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:

  • "results"
    • "wrenches": Contains a single child 'wrench' that is an unsorted list of Golden Wrenches
      • "steamID": 64-bit Steam ID of the owner of the wrench
      • "timestamp": Seconds since 1/1/1970 of the time the wrench was crafted
      • "itemID": ItemID of the wrench. This will match the itemID returned by GetPlayerItems for this user.
      • "wrenchNumber": The serial number on the wrench. This will match the serial number attribute on the item itself.

See Also

Retrieved from "https://wiki.teamfortress.com/w/index.php?title=WebAPI&oldid=43951"