API:2/characters

From Guild Wars 2 Wiki
Jump to: navigation, 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?page=0)

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, with the exception of v2/characters/:id/heropoints and v2/characters/:id/sab.

  • v2/characters/:id/backstory
  • v2/characters/:id/core
  • v2/characters/:id/crafting
  • v2/characters/:id/equipment
  • v2/characters/:id/heropoints
  • v2/characters/:id/inventory
  • v2/characters/:id/recipes
  • v2/characters/:id/sab
  • v2/characters/:id/skills
  • v2/characters/:id/specializations
  • v2/characters/:id/training

There are additionally unique entries such as title, wvw_abilities, equipment_pvp

Backstory

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

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.
  • 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
    • slot (string) - The equipment slot in which the item is slotted. 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
    • 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

Heropoints

Returns an array of strings marking each hero point obtained by the character. Can be checked against entries 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.
      • 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
      • 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 (number) - The world id
    • mode (string) - The difficulty mode cleared
    • world (number) - The world number
    • zone (number) - The zone number
  • unlocks (array) - Contains objects describing the unlocks on the given character. (list of possible values visible on [1]
    • id (number) - The id of the unlock
    • name (string) - The name of the upgrade
  • songs (array) - Contains the objects of unlocked songs on the character
    • id (number) - 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

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": [...]
 }