API:2/characters

From Guild Wars 2 Wiki
Jump to navigationJump to search

/v2/characters

HTTP method
GET
Format
json
API version
version 2
Release date
2015-05-22
Scope
account
characters
Optional
none

This resource returns information about characters attached to a specific account.

Parameters

  • access_token - (optional) If the API key is not specified in the request header, it can be specified here.

Response

If the endpoint is accessed without any parameters (/v2/characters), it will return an array of characters by name.

Characters can be requested specifically via the ids parameter, or by specifying them percent-encoded in the next URI component. (e.g. /v2/characters/My%20Character)

To retrieve all the characters on an account, pagination can be used. (/v2/characters?ids=all)

By opening the endpoint via /v2/characters/<character name>, a summary of the character information will be given. This is taken from each sub-endpoint listed below. Schema version 2019-12-19T00:00:00.000Z or later, this endpoint will include v2/characters/:id/buildtabs and v2/characters/:id/equipmenttabs and will no longer include v2/characters/:id/skills and v2/characters/:id/specializations

The following sub-endpoints are available, but are not included in v2/characters/<character name>:

There are additionally unique entries such as wvw_abilities, equipment_pvp, build_tabs_unlocked, active_build_tab, equipment_tabs_unlocked, and active_equipment_tab

Backstory

  • backstory (array) - An array of strings representing backstory answer IDs pertaining to the questions answered during character creation. References /v2/backstory/answers.

Build Tabs

  • build_tabs (array) - An array containing an object for each build tab the character has.
    • tab (number) - The "id" of this tab. (The position at which it resides.)
    • is_active (boolean) - Whether or not this is the tab selected on the character currently.
    • build (object) - Contains detailed information about the build.
      • name (string) - The name given to the build.
      • profession (string) - The characters profession. Resolvable against /v2/professions.
      • specializations (array of objects) - Three objects providing information about the characters selected specializations.
        • id (number) - The specialization id or null if none is selected. Resolvable against /v2/specializations.
        • traits (array of numbers) - Three trait ids or null in places where none is selected. Resolvable against /v2/traits.
      • skills (object) - Contains information about the characters selected skills. All values may be resolved against /v2/skills.
        • heal (number) - The id of the heal skill or null if none is selected.
        • utilities (array of numbers) - Three utility skill ids or null in places where none is selected.
        • elite (number) - The id of the elite skill or null if none is selected.
      • aquatic_skills (object) - Contains information about the characters selected underwater skills. The structure is the same as the one of skills above.
      • legends (array of strings, optional) - Included for revenants only. Two legend ids or null in places where none is selected. Resolvable against /v2/legends.
      • aquatic_legends (array of strings, optional) - Included for revenants only. The structure is the same as the one of legends above.
      • pets (object) (optional) - Included for rangers only. Containers information about the characters selected pets. Resolvable against /v2/pets.
        • terrestrial (array of integers) - Containers the two pet ids the ranger has equipped for terrestrial combat.
        • aquatic (array of integers) - Containers the two pet ids the ranger has equipped for aquaticcombat.

Core

  • name (string) - The character's name.
  • race (string) - The character's race. Possible values:
    • Asura
    • Charr
    • Human
    • Norn
    • Sylvari
  • gender (string) - The character's gender. Possible values:
    • Male
    • Female
  • profession (string) - The character's profession. Possible values:
    • Elementalist
    • Engineer
    • Guardian
    • Mesmer
    • Necromancer
    • Ranger
    • Revenant
    • Thief
    • Warrior
  • level (integer) - The character's level.
  • guild (string, optional) - The guild ID of the character's currently represented guild.
  • age (integer) - The amount of seconds this character was played.
  • last_modified (string) – An ISO-8601 standard timestamp of when the account information last changed as perceived by the API. This field is only present when a Schema version of 2019-02-21T00:00:00Z or later is requested.[1]
  • created (string) - ISO 8601 representation of the character's creation time.
  • deaths (integer) - The amount of times this character has been defeated.
  • title (number, optional) - The currently selected title for the character. References /v2/titles.

Crafting

  • crafting (array) - An array containing an entry for each crafting discipline the character has unlocked
    • discipline (string) - The name of the discipline. Possible values:
      • Armorsmith
      • Artificer
      • Chef
      • Huntsman
      • Jeweler
      • Leatherworker
      • Scribe
      • Tailor
      • Weaponsmith
    • rating (integer) - The current crafting level for the given discipline and character
    • active (boolean - true/false) - Describes if the given discipline is currently active or not on the character.

Equipment

  • equipment (array) - An array containing an entry for each piece of equipment currently on the selected character.
    • id (integer) - The item id, resolvable against /v2/items
    • count (integer) (optional) - The unlock count of this item when location is LegendaryArmory. Available on schema 2019-12-19T00:00:00.000Z or later.
    • slot (string) - The equipment slot in which the item is slotted. This value is optional on schema 2019-12-19T00:00:00.000Z or later, will be missing if equipment is in an inactive tab. Possible values:
      • HelmAquatic
      • Backpack
      • Coat
      • Boots
      • Gloves
      • Helm
      • Leggings
      • Shoulders
      • Accessory1
      • Accessory2
      • Ring1
      • Ring2
      • Amulet
      • WeaponAquaticA
      • WeaponAquaticB
      • WeaponA1
      • WeaponA2
      • WeaponB1
      • WeaponB2
      • Sickle
      • Axe
      • Pick
    • infusions (array) (optional) - returns an array of infusion item ids which can be resolved against /v2/items
    • upgrades (array) (optional) - returns an array of upgrade component item ids which can be resolved against /v2/items
    • skin (integer) (optional) - Skin id for the given equipment piece. Can be resolved against /v2/skins
    • stats (object) (optional) - Contains information on the stats chosen if the item offers an option for stats/prefix.
      • id (integer) - The itemstat id, can be resolved against /v2/itemstats
      • attributes (object) - Contains a summary of the stats on the item.
        • Power (integer) (optional) - Shows the amount of power given
        • Precision (integer) (optional) - Shows the amount of Precision given
        • Toughness (integer) (optional) - Shows the amount of Toughness given
        • Vitality (integer) (optional) - Shows the amount of Vitality given
        • Condition Damage (integer) (optional) - Shows the amount of Condition Damage given
        • Condition Duration (integer) (optional) - Shows the amount of Condition Duration given
        • Healing (integer) (optional) - Shows the amount of Healing Power given
        • BoonDuration (integer) (optional) - Shows the amount of Boon Duration given
    • binding (string) (optional) - describes which kind of binding the item has. Possible values:
      • Character
      • Account
    • location (string) - describes where this item is stored. Available on schema 2019-12-19T00:00:00.000Z or later. Possible values:
      • Equipped - equipped in the active tab.
      • Armory - equipped in an inactive tabs.
      • EquippedFromLegendaryArmory - if the item is stored in the account-wide legendary armory, but equipped in the active tab.
      • LegendaryArmory - if the item is stored in the account-wide legendary armory, but equipped in an inactive tabs.
    • tabs (array of numbers) - identifies which tabs this particular item is reused in. Available on schema 2019-12-19T00:00:00.000Z or later.
    • charges (number) (optional) - The amount of charges remaining on the item.
    • bound_to (string) (optional, only if character bound) - Name of the character the item is bound to.
    • dyes (array of numbers) - Array of selected dyes for the equipment piece. Values default to null if no dye is selected. Colors can be resolved against v2/colors

Equipment Tabs

  • equipment_tabs (array) - An array containing an object for each equipment tab the character has.
    • tab (number) - The "id" of this tab. (The position at which it resides.)
    • name (string) - The name given to the equipment combination.
    • is_active (boolean) - Whether or not this is the tab selected on the character currently.
    • equipment (array of objects) - Contains an object for each equiped piece of equipment.
      • id (number) - The item id of the equipment piece. Resolvable against /v2/items.
      • slot (string) - In which slot the equipment piece is equiped. Possible values:
        • Helm
        • Shoulders
        • Coat
        • Gloves
        • Leggings
        • Boots
        • WeaponA1
        • WeaponA2
        • WeaponB1
        • WeaponB2
        • Backpack
        • Accessory1
        • Accessory2
        • Amulet
        • Ring1
        • Ring2
        • HelmAquatic
        • WeaponAquaticA
        • WeaponAquaticB
      • skin (number, optional) - The skin id of the skin transmuted onto the equipment piece. Resolvable against /v2/skins.
      • upgrades (array of numbers, optional) - The item ids of the upgrade components sloted in the weapon. Resolvable against /v2/items.
      • infusions (array of numbers, optional) - The item ids of the infusions sloted in the weapon. Resolvable against /v2/items.
      • binding (string, optional) - The binding of the item. Possible values:
        • Account
        • Character
      • bound_to (string, optional) - The name of the character to which the item is bound.
      • location (string) - Either Equipped or Armory.
      • dyes (array of numbers, optional) - Four dye ids representing the dyes used in the dye slots of the equipment piece or null if a dye slot is unavailable for a piece. Resolvable against /v2/colors.
      • stats (object, optional) - Contains detailed information on the weapon stats.
        • id (number) - The id of the wepons stats. Resolvable against /v2/itemstats.
        • attributes (object) - Contains the weapon attributes in the form of key value pairs with the key being the attribute name and the value itself.
    • equipment_pvp (object) - Contains the following key-value pairs:
      • amulet (number) - resolve id against v2/pvp/amulets.
      • rune (number) - resolve id against v2/items.
      • sigils (array of numbers) - resolve ids against v2/items. Will contain nulls for unequipped items.
        • Sigils are provided in the order [<primary weapon sigil 1>, <secondary weapon sigil 1>, <primary weapon sigil 2>, <secondary weapon sigil 2>].

Heropoints

Returns an array of strings marking each hero point obtained by the character. Can be checked against skill_challenges in /v2/continents maps.

Inventory

  • bags (array) - Contains one object structure per bag in the character's inventory
    • id (integer) - The bag's item id which can be resolved against /v2/items
    • size (integer) - The amount of slots available with this bag.
    • inventory (array) - Contains one object structure per item, object is null if no item is in the given bag slot.
      • id (integer) - The item id which can be resolved against /v2/items
      • count (integer) - Amount of item in the stack. Minium of 1, maximum of 250.
      • charges (integer) (optional) - The number of charges on an item.
      • infusions (array) (optional) - returns an array of infusion item ids which can be resolved against /v2/items
      • upgrades (array) (optional) - returns an array of upgrade component item ids which can be resolved against /v2/items
      • skin (integer) (optional) - Skin id for the given equipment piece. Can be resolved against /v2/skins
      • stats (object) (optional) - Contains information on the stats chosen if the item offers an option for stats/prefix.
        • id (integer) - The itemstat id, can be resolved against /v2/itemstats.
        • attributes (object) - Contains a summary of the stats on the item.
          • Power (integer) (optional) - Shows the amount of power given
          • Precision (integer) (optional) - Shows the amount of Precision given
          • Toughness (integer) (optional) - Shows the amount of Toughness given
          • Vitality (integer) (optional) - Shows the amount of Vitality given
          • Condition Damage (integer) (optional) - Shows the amount of Condition Damage given
          • Condition Duration (integer) (optional) - Shows the amount of Condition Duration given
          • Healing (integer) (optional) - Shows the amount of Healing Power given
          • BoonDuration (integer) (optional) - Shows the amount of Boon Duration given
      • dyes (array of numbers) (optional) - Array of selected dyes for the equipment piece. Values default to null if no dye is selected. Colors can be resolved against v2/colors
      • binding (string) (optional) - describes which kind of binding the item has. Possible values:
        • Character
        • Account
      • bound_to (string) (optional, only if character bound) - Name of the character the item is bound to.

Skills

  • skills (object) - contains the pve, pvp, and wvw objects for the current utilities equipped.
    • pve (object) - contains the information on each slotted utility for PvE
      • heal (integer) - contains the skill id for the heal skill, resolvable against /v2/skills.
      • utilities (array of integers) - each integer corresponds to a skill id for the equipped utilities, resolvable against /v2/skills.
      • elite (integer) - contains the skill id for the elite skill, resolvable against /v2/skills.
      • legends (array of strings) (Revenant only) - each string corresponds to a Revenant legend, resolvable against /v2/legends.
    • pvp (object) - contains the information on each slotted utility for PvP
      • heal (integer) - contains the skill id for the heal skill, resolvable against /v2/skills.
      • utilities (array of integers) - each integer corresponds to a skill id for the equipped utilities, resolvable against /v2/skills.
      • elite (integer) - contains the skill id for the elite skill, resolvable against /v2/skills.
      • legends (array of strings) (Revenant only) - each string corresponds to a Revenant legend, resolvable against /v2/legends.
    • wvw (object) - contains the information on each slotted utility for WvW
      • heal (integer) - contains the skill id for the heal skill, resolvable against /v2/skills.
      • utilities (array of integers) - each integer corresponds to a skill id for the equipped utilities, resolvable against /v2/skills.
      • elite (integer) - contains the skill id for the elite skill, resolvable against /v2/skills.
      • legends (array of strings) (Revenant only) - each string corresponds to a Revenant legend, resolvable against /v2/legends.

Specialization

  • specializations (object) - contains the pve, pvp, and wvw objects for the current specializations and traits equipped.
    • pve (array) - contains the information on each slotted specialization and trait for PvE
      • id (integer) - Specialization id, can be resolved against /v2/specializations.
      • traits (array of integers) - returns ids for each selected trait, can be resolved against /v2/traits.
    • pvp (array) - contains the information on each slotted specialization and trait for PvP
      • id (integer) - Specialization id, can be resolved against /v2/specializations.
      • traits (array of integers) - returns ids for each selected trait, can be resolved against /v2/traits.
    • wvw (array) - contains the information on each slotted specialization and trait for WvW
      • id (integer) - Specialization id, can be resolved against /v2/specializations.
      • traits (array of integers) - returns ids for each selected trait, can be resolved against /v2/traits.

Training

  • training (array) - contains objects for each skill tree trained
    • id (integer) - Skill tree id, can be compared against the training section for each /v2/professions.
    • spent (integer) - Shows how many hero points have been spent in this tree
    • done (boolean - true/false) - States whether or not the tree is fully trained.

Super Adventure Box (sab)

  • zones (array) - Contains objects describing which worlds, and in which difficult, have been cleared
    • id (integer) - The world id
    • mode (string) - The difficulty mode cleared
    • world (integer) - The world number
    • zone (integer) - The zone number
  • unlocks (array) - Contains objects describing the unlocks on the given character. (list of possible values visible on [1]
    • id (integer) - The id of the unlock
    • name (string) - The name of the upgrade
  • songs (array) - Contains the objects of unlocked songs on the character
    • id (integer) - The id of the song
    • name (string) - The name of the song

Extras

  • wvw_abilities (array) - contains information on each trained wvw ability
    • id (integer) - ability id, can be resolved against /v2/wvw/abilities
    • rank (integer) - current rank for the given ability.
  • equipment_pvp (object) - Contains information on character's pvp equipment setup.
    • amulet (integer) - Id for the equipped pvp amulet, can be resolved against /v2/pvp/amulets.
    • rune (integer) - Id for the equipped pvp rune, can be resolved against /v2/items.
    • sigils (array of integers) - Returns the id for all equipped pvp sigils. Can be resolved against /v2/items.
  • flags (array of strings) - Returns character flags. Possible values:
    • Beta - Beta character for testing period of add-ons

The following fields are available on schema version 2019-12-19T00:00:00.000Z or later.

  • build_tabs_unlocked (integer) - Number of build tabs unlocked for this character.
  • active_build_tab (integer) - Tab id of currently active build.
  • equipment_tabs_unlocked (integer) - Number of equipment tabs unlocked for this character.
  • active_equipment_tab (integer) - Tab id of currently active equipment.

Examples

Request

 https://api.guildwars2.com/v2/characters/<character name>/<additional endpoint>
 Authorization: Bearer <API key>

 https://api.guildwars2.com/v2/characters/<character name>/<additional endpoint>?access_token=<API key>

Backstory 

 {
   "backstory": [
       "7-54",
       "12-75",
       "186-162",
       "11-72",
       "10-67"
   ]
 }

Core 

 {
   "name": "<character name>",
   "race": "Asura",
   "gender": "Male",
   "profession": "Elementalist",
   "level": 80,
   "guild": "<guild id>",
   "age": 12631700,
   "created": "2013-04-27T04:15:00Z",
   "deaths": 9193,
   "title": 251
 }

Crafting 

 {
   "crafting": [
       {
           "discipline": "Artificer",
           "rating": 500,
           "active": true
       },
       {
           "discipline": "Huntsman",
           "rating": 12,
           "active": false
       },
       {
           "discipline": "Jeweler",
           "rating": 136,
           "active": false
       },
       {
           "discipline": "Tailor",
           "rating": 500,
           "active": true
       }
   ]
 }

Equipment 

 {
   "equipment": [
       {
           "id": 47874,
           "slot": "HelmAquatic",
           "upgrades": [
               24836
           ],
           "binding": "Character",
           "bound_to": "<Character name>"
       },
       {
           "id": 72309,
           "slot": "Backpack",
           "infusions": [
               77310,
               49433
           ],
           "skin": 6561,
           "stats": {
               "id": 584,
               "attributes": {
                   "Power": 63,
                   "Precision": 40,
                   "CritDamage": 40
               }
           },
           "binding": "Account"
       },
       {
           "id": 48079,
           "slot": "Coat",
           "upgrades": [
               24836
           ],
           "infusions": [
               49432
           ],
           "skin": 5719,
           "binding": "Account"
       },
       {...},
       {
           "id": 22997,
           "slot": "Sickle",
           "binding": "Account",
           "charges": 31
       },
       {
           "id": 23000,
           "slot": "Axe",
           "binding": "Account",
           "charges": 7
       },
       {
           "id": 48933,
           "slot": "Pick",
           "binding": "Account"
       }
   ]
 }

Heropoints 

 [
   "0-0",
   "0-2",
   ...,
   "0-247",
   "0-248"
 ]

Inventory 

 {
   "bags": [
       {
           "id": 38013,
           "size": 20,
           "inventory": [
               {
                   "id": 76072,
                   "count": 1,
                   "binding": "Character",
                   "bound_to": "<Character name>"
               },
               {...},
               {
                   "id": 43451,
                   "count": 11
               }
           ]
       },
       {...},
       {
           "id": 67518,
           "size": 20,
           "inventory": [
               {...},
               {
                   "id": 849,
                   "count": 1
               },
               null,
               null,
               null,
               null,
               null,
               null
           ]
       }
   ]
 }

Skills 

 {
   "skills": {
       "pve": {
           "heal": 29535,
           "utilities": [
               5734,
               5567,
               5542
           ],
           "elite": 29968
       },
       "pvp": {
           "heal": 29535,
           "utilities": [
               30432,
               30662,
               29948
           ],
           "elite": 29968
       },
       "wvw": {
           "heal": 29535,
           "utilities": [
               5734,
               5536,
               5542
           ],
           "elite": 29968
       }
   }
 }

Specialization 

 {
   "specializations": {
       "pve": [
           {
               "id": 31,
               "traits": [
                   296,
                   325,
                   1510
               ]
           },
           {...},
           {
               "id": 48,
               "traits": [
                   1952,
                   2015,
                   1986
               ]
           }
       ],
       "pvp": [...],
       "wvw": [...]
   }
 }

Training 

 {
   "training": [
       {
           "id": 33,
           "spent": 22,
           "done": true
       },
       {...},
       {
           "id": 31,
           "spent": 250,
           "done": true
       }
   ]
 }

Sab 

 {
   "zones": [
       {
           "id": 1,
           "mode": "normal",
           "world": 1,
           "zone": 1
       },
       ...
       {
           "id": 13,
           "mode": "infantile",
           "world": 1,
           "zone": 1
       },
       ...
       {
           "id": 25,
           "mode": "tribulation",
           "world": 1,
           "zone": 1
       },
       ...
   ],
   "unlocks": [
       {
           "id": 1,
           "name": "chain_stick"
       },
       ...
   ],
   "songs": [
       {
           "id": 1,
           "name": "secret_song"
       },
       ...
   ]
 }

Overview 

 {
   "name": "<character name>",
   "race": "Asura",
   "gender": "Male",
   "profession": "Elementalist",
   "level": 80,
   "guild": "<guild id>",
   "age": 12631700,
   "created": "2013-04-27T04:15:00Z",
   "deaths": 9193,
   "crafting": [...],
   "title": 251,
   "backstory": [...],
   "wvw_abilities": [
       {
           "id": 14,
           "rank": 4
       },
       {...},
       {
           "id": 2,
           "rank": 4
       }
   ],
   "specializations": {...},
   "skills": {...},
   "equipment": [...],
   "recipes": [
       1,
       2,
       ...,
       11878,
       11887
   ],
   "equipment_pvp": {
       "amulet": 29,
       "rune": 21212,
       "sigils": [
           21154,
           65230,
           21152,
           21124
       ]
   },
   "training": [...],
   "bags": [...]
 }
API
Account
achievements • bank • build storage • daily crafting • dungeons • dyes • finishers • gliders • home instance (cats • nodes) • legendary armory • luck • mail carriers • map chests • masteries • mastery/points • materials • minis • mounts (types • skins) • novelties • outfits • progression • PvP heroes • raids • recipes • shared inventory • jade bots • skiffs • skins • titles • wallet • wizard's vault (listings • daily • weekly • special) • world bosses
Achievements
achievements • categories • daily (tomorrow) • groups
Characters
backstory • build tabs • core • crafting • equipment • equipment tabs • hero points • inventory • quests • recipes • Super Adventure Box • skills • specializations • training
Daily Rewards
daily crafting • map chests • world bosses
Events
event detailsv1
Game mechanics
colors • currencies • dungeons • emotes • legends • legendary armory • masteries • pets • professions • races • raids • skills • specializations • titles • traits
Guild
emblem (backgrounds • foregrounds) • info (log • members • ranks • stash • storage • teams • treasury • upgrades) • permissions • search • upgrades
Home instance
cats • nodes
Items
items • item stats • materials • recipes (search)
Maps
continents • maps
Story
backstory (answers • questions) • quests • stories (seasons)
Structured PvP
amulets • games • heroes • ranks • seasons (leaderboards) • standings • stats
Commerce (Trading post)
delivery • exchange • listings • prices • transactions
Wardrobe
finishers • gliders • jade bots • mail carriers • minis • mounts (skins • types) • novelties • outfits • skiffs • skins
Wizard's Vault
listings • objectives
World vs. World
abilities • matches (guild stats • match stats • overview • scores [?] • team stats) • objectives • ranks • upgrades • worlds
Miscellaneous
build • create subtoken • files • quaggans • token info
Additional services
assets • render • tiles
Help topics
Best practices • Maps • Mumble Link
  1. ^ https://gitter.im/arenanet/api-cdi?at=5c7091129e430b3086af0943
Retrieved from "https://wiki.guildwars2.com/index.php?title=API:2/characters&oldid=2609825"