API CHANGES

This topic is used to document changes in the API so that one can receive email notifications on changes to the API.

To do this, click the "Watch this topic" button on the lower left of this screen.

 

New changes:

1. You may use regular expressions within a Query String using the '*' modifier
2. <span style="text-decoration: line-through;">c:case Query Command *does* work, but is only applicable when using regular expressions  (see below)
3. You may now use c:resolve=warders to resolve the beasts and their spells (only relevant for Beastlord)

-dan

 

Okay...the c:case is being deprecated again.  It is complicated because it only really applied to a regular expression and there are much better (and standard) ways to express that.

Instead of using field=*blah&c:case=false, you should use field=i/blah/

field=i/blah/ would return any object whose field contains any form of "blah" ("Blah", "bLah", etc.).

field=/blah/ would return any object whose field contains the characters "blah" ("Ablahahaha", "Blahblahblah" but not "Blahahaha").

-dan

 

A new Query Command has been added!

If you include c:attachments, you will be able to access the binary files (usually an image) that are attached to an object.

Here is an example:

census.daybreakgames.com/xml/get/eq2/character/1297081049216?c:show=displayname&c:attachments=all

(The "http://" has been removed to defeat the forum's auto URL truncation)

This will include a element that looks like:

Code:

<attached_files>
  <paperdoll>
    <paperdoll_default contentType="image/png" description="Cleamolette" extension="png" last_update="1323875580" location="Frostfang Sea" server="Storms" url="census.daybreakgames.com/img/eq2/character/1297081049216/paperdoll" />
  </paperdoll>
  <housethumb>
    <housethumb_5440582801589566468 contentType="image/jpeg" description="Mistmoore 5" extension="jpg" last_update="1323862617" location="Mistmoore 5" server="Storms" url="census.daybreakgames.com/img/eq2/character/1297081049216/housethumb/5440582801589566468" />
  </housethumb>
  <headshot>
    <headshot_default contentType="image/png" description="Cleamolette" extension="png" last_update="1323875580" location="Frostfang Sea" server="Storms" url="census.daybreakgames.com/img/eq2/character/1297081049216/headshot" />
  </headshot>
</attached_files>

The url attribute provides you with a fully qualified URL that you can use in your website or application to retrieve the image.

In JSON, this format translates directly into a Dictionary which you can access directly through dot notation...

attached_files.petpaperdoll.reptile.url

...or as an array

attached_files.headshot[0].url

CAVEAT: This will only show for characters that have been updated recently until we run a script that updates existing records with the attachment information (that will happen sometime tomorrow).

The available (game-specific) categories are:

• paperdoll - a picture of the character
• headshot - a picture of the character from the neck up
• housethumb - thumbnail for a house published in-game for ranking
• petpaperdoll - a picture of a pet (currently only usable for Beastlords)

 

Updated the c:attachments API (post above) as it changed from a list to a dictionary type of storage.

-dan

 

The name of some of the item.modifiers has been changed.  

Previously, you might find...

<Subjugation type="skill" value="28"/>

This is problematic as the name of the skill is localized and not consistent across each server (and it some cases, not XML safe).

These have been changed to use the syntax:

<skill displayname="Subjugation" type=skill value="28"/>

This went out live on December 21, 2011.  Sorry for the delayed notice.

-dan

 

This change will be reverted next Tuesday, January 24, 2012.

We are going to change the block on objects in the item collection to be much more consistent with the rest of the API.

Code:

<modifiers>
  <modifier displayname="Crit Bonus" name="critbonus" type="modifyproperty" value="5.100000"/>
  <modifier displayname="Potency" name="basemodifier" type="modifyproperty" value="5.100000"/>
  <modifier displayname="Ability Casting Speed" name="spelltimecastpct" type="modifyproperty" value="6"/>
  <modifier displayname="Critical Mitigation" name="criticalmitigation" type="modifyproperty" value="16.799999"/>
  <modifier displayname="Ministration" type="skill" value="31"/>
  <modifier displayname="Ordination" type="skill" value="31"/>
  <modifier displayname="Wisdom" name="wisdom" type="attribute" value="102"/>
  <modifier displayname="Stamina" name="stamina" type="attribute" value="102"/>
</modifiers>

Previously, these modifiers did not follow a consistent pattern and there was a element (see previous post in this thread). This new patter is much more generic and scalable to new modifiers that may come in the future.

-dan

 

A new c:resolve command is now available for EQ2 characters: "statistics"

Consider the following call:

census.daybreakgames.com/xml/get/eq2/character/?c:limit=1&c:show=statistics

Code:

<?xml version='1.0' encoding='UTF-8'?><characters>  <character id="2168961825756">    <statistics>      <kills value="0" />      <deaths value="0" />      <max_melee_hit value="0" weapon="4294967295" />      <max_magic_hit spell="4294967295" value="0" />      <rare_harvests value="0" />      <items_crafted value="0" />    </statistics>  </character></characters>

If you use the c:resolve=statistics Query Command, you will see the ranking of the character for the statistics that are being tracked.

census.daybreakgames.com/xml/get/eq2/character/?c:limit=1&c:show=statistics&c:resolve=statistics

Code:

<?xml version='1.0' encoding='UTF-8'?><characters>  <character id="2168961825756">    <statistics>      <kills value="0">        <world average="5798" max="3914942" of="96798" rank="80657">          <class average="2862" max="372633" of="3888" rank="2934" />        </world>      </kills>      <deaths value="0">        <world average="80" max="19214" of="96798" rank="58936">          <class average="55" max="12712" of="3888" rank="2037" />        </world>      </deaths>      <max_melee_hit value="0" weapon="4294967295">        <world average="30897" max="65531408" of="96798" rank="80145">          <class average="3839" max="445107" of="3888" rank="2931" />        </world>      </max_melee_hit>      <max_magic_hit spell="4294967295" value="0">        <world average="692661" max="524162816" of="96798" rank="69359">          <class average="431548" max="79708264" of="3888" rank="1748" />        </world>      </max_magic_hit>      <rare_harvests value="0" />      <items_crafted value="0" />    </statistics>  </character></characters>

These results are available in JSON and YAML formats as well as in XML (shown).

These are the rankings of the character within their world ("server") and their class within their world.  The of attribute is the number of characters that make up the total list of characters that 

You may also resolve only particular statistics (such as "kills") with c:resolve=statistics(kills). This can be a comman delimited list from {kills,deaths,max_melee_hit,max_magic_hit}.

 

A new, optional change has been made to the URL syntax effective immediately.

If you add the a string "s:something" at the beginning of your URL, it can be used to identify request coming from a particular provider.

For instance:

census.daybreakgames.com/xml/get/eq2/character/?c:limit=1

...would work identically as...

census.daybreakgames.com/s:something/xml/get/eq2/character/?c:limit=1

This will be especially useful as the system will send a notification email with error detail should an error occur for that request.  These messages will be sent to the email addresses registered with SOE for that ID.  The message should provide you with useful information to help you fix problems.

You should NOT use a "/" character in your string.  Just about all other characters should be okay as long as you prefix it with s:

-dan

 

A change to the JSON results will be coming soon.  This is currently available by specifying json-x as the format.

For example:

census.daybreakgames.com/json-x/get/eq2/item/?c:limit=1

Currently, JSON results always come back as a top-level array of JSON objects.  

[  { item: { ... } },  { item: { ... } },  { item: { ... } }]

If there are no result, it is an empty array [].  This is the original design of our system and it has served us well.  However, there are new requirements that mean that we would need to provide more information back in each result.

We are going to change the returned format for JSON to be a dictionary.  The data that would have been returned in the previous format would be in an entry named as the plural form of the collection you are querying. 

{  items: [    { item: { ... } },    { item: { ... } },    { item: { ... } }  ]}

If there are no results returned, the items will be an empty array.  If there are no results due to an error condition, the result will be null.

 

A change has been made to the limits returned in a query.

By default, the API will return the first item found from a query - defaulting to c:limit=1 - instead of 25.  This has the benefit of providing a result as quickly as possible (it will return as soon as the limit is found), even for items without an index.  You should specify the c:limit that you would like.

For characters, the limit is determined as follows.  If you use c:show (specifying what you would like), you may get up to 5000 objects back.  If you don't use a c:show (asking for all info), your limit will be 100.

 

Guild Changes

An index has been added to the guild collection: worldid + dbid.  This means that you can more efficiently look for guilds by their world-unique identifier.

Also, we have added a c:resolve on guild to resolve character information from its members.  This should remove work to have to use the dbid in the first place.

census.daybreakgames.com/xml/get/eq2/guild/?c:resolve=members

By default, this will only resolve the identifier of each member.  Of course, you could add more information into the resolve by adding them as parameters to the c:resolve.

census.daybreakgames.com/xml/get/eq2/guild/?c:resolve=members(displayname,type)

-dan

 

We are going to revert the change to the block on objects in the*item*collection to be much more consistent with the rest of the API.

Code:

<modifiers>
<critbonus displayname="Crit Bonus" type="modifyproperty" value="5.100000"/>
<basemodifier displayname="Potency" type="modifyproperty" value="5.100000"/>
<spelltimecastpct displayname="Ability Casting Speed" type="modifyproperty" value="6"/>
<criticalmitigation displayname="Critical Mitigation" type="modifyproperty" value="16.799999"/>
</modifiers>

All props go to Dethdlr which tested this change and found that the new format, while clean and easy to parse, made it impossible to search modifiers (and related elements in <skills>)*across multiple classes.

This change will occur next Tuesday morning, January 24th.

-dan

 

We have had a continuous challenge when trying to manage lists of data. When should things be an "array" versus a large dictionary. This has been the source of frustration around the recent changes to modifiers.

Another aspect of this problem is trying to name things correctly. In general, we use the plural form of a item word to represent that it is a collection of that item. For instance, "items" is a bunch of "item" objects. This is used all over the API - equipmentslots/equipmentslot, etc.

This pattern really breaks down when the plural form is more complicated than adding an "s" to the singular form. Think: "class/classes" or "property/properties". This is even more difficult because we store the plural form in the database and derive the singular from it. It would be easier if we went the other direction.

We need to make a change that fixes this problem in a very deterministic way that is not tied to english languages anachronisms. It should also make it clearer when the items are an array instead of a dictionary.

All items in the database will be represented by the singular form of the object holding the data. When a collection of these objects are represented in the data feed, they will be represented by [objectname]_list. If an object has a dictionary of attributes (or sub-objects), it can be represented by the most appropriate name - singular or plural.

Examples:
This is most visible in XML, which describes the container relationship of objects:

Code:

<equipmentslot_list>
<equipmentslot id="0" name="primary">* *
*<item id="1107134169" />
</equipmentslot>
<equipmentslot id="1" name="secondary">* *
*<item id="1107134169" />
</equipmentslot>
<equipmentslot id="3" name="chest">* *
*<item id="2276994386" />
</equipmentslot>
<equipmentslot id="7" name="legs">* *
*<item id="730666633" />
</equipmentslot>
<equipmentslot id="8" name="feet">* *
*<item id="3731234898" />
</equipmentslot>
<equipmentslot id="16" name="ranged">* *
*<item id="3641368917" />
</equipmentslot>
<equipmentslot id="17" name="ammo">
<item id="3760579470" />
</equipmentslot>
<equipmentslot id="20" name="activate1">* *
*<item id="2387617990" />
</equipmentslot>
<equipmentslot id="22" name="food">* *
*<item id="2330290915" />
</equipmentslot>
<equipmentslot id="23" name="drink">* *
*<item id="2116100626" />
</equipmentslot>
</equipmentslotList>

In JSON, the results will show the "_list" name (replacing the plural form) followed by an array ([]) of that object. This is actually accurate to how the data is stored (a good thing).

"equipmentslot_list": [* {"item": {"id": 1107134169}, "id": 0, "name": "primary"},
{"item": {"id": 1107134169}, "id": 1, "name": "secondary"},
{"item": {"id": 2276994386}, "id": 3, "name": "chest"},
{"item": {"id": 730666633}, "id": 7, "name": "legs"},
{"item": {"id": 3731234898}, "id": 8, "name": "feet"},
{"item": {"id": 3641368917}, "id": 16, "name": "ranged"},
{"item": {"id": 3760579470}, "id": 17, "name": "ammo"},
{"item": {"id": 2387617990}, "id": 20, "name": "activate1"},
{"item": {"id": 2330290915}, "id": 22, "name": "food"},
{"item": {"id": 2116100626}, "id": 23, "name": "drink"}]

This pattern will now be consistent whether there is zero, one or multiple items within the list. Referencing items within the JSON results should use the plural form, which is the similar to the current format (only using List instead of a plural form)...

equipmentslot_list[0] instead of equipmentslots[0]

The other impact on this is that c:resolve commands will need to change to use the singular form of the object (c:resolve=equipmentslot) instead of the plural form of the object name.

This change will take place [strikethru]this afternoon[/strikethru] on the next game update, problably Tuesday, Feb 1st. *New updates will be in the new form immediately and existing data will be migrated to the new format over a few hours.

<span style="color: #ff0000;">UPDATE:*We are working with the game team to clean up the data and add a couple more stats to the feed. *This is a rather dramatic change and I would like to get it right.

<span style="color: #ff0000;">Also, "List" is being changed to "_list" to match the naming and capitalization form already in use by the game data.

 

New Query Command: c:count

Example use: search for all characters with a name that contains the string "bob" (case insensitively)

name.first=i/bob/&c:show=displayname&c:count=1

This will return only one character, but it will indicate that the results have been limited to 1 object (no c:limit was defined, so it defaults to 1), but it show the count so that you can do paging.

{  "characters": [    {      "displayname": "Abob (Butcherblock)",       "id": 463858446030    }  ],   "count": 774,   "limit": 1,   "returned": 1}

-dan

 

New output format: jml

In addition to "xml", "json" and "yaml" (existing formats), you may also request data in "jml".  This is the JSON data format, but in a "beautified" format that is easier for humans to read.  This means that you don't have to run the output through a plugin or filter just to make sense of the JSON data.

-dan

 

What can you c:resolve?
We recently added the ability to query the API for the list of available collections. *You do this by omitting the collection...
census.daybreakgames.com/xml/get/eq2/

The returned result now includes the fields that can be used for c:resolve.

Code:

<collections name="character">
<resolve_list>
<resolve>spells</resolve>
<resolve>factions</resolve>
<resolve>appearanceslots</resolve>
<resolve>equipmentslots</resolve>
<resolve>achievements</resolve>
<resolve>warders</resolve>
<resolve>statistics</resolve>
</resolve_list>
</collections>

The value that is in the element tells you what to use for c:resolve command. *Remember, you can c:resolve more than one field by using a comma delimited list.
-dan

 

New Query Command: c:explain

If you are getting a slow result when querying the API, you can now use c:explain to see if there might be a reason.

Example Usage: census.daybreakgames.com/jml/get/eq2/character/?c:explain=1

{  "allPlans": [    {      "cursor": "BasicCursor",       "indexBounds": {}    }  ],   "cursor": "BasicCursor",   "indexBounds": {},   "indexOnly": false,   "isMultiKey": false,   "millis": 0,   "n": 1,   "nChunkSkips": 0,   "nYields": 0,   "nscanned": 1,   "nscannedObjects": 1}

If you see "cursor": "BasicCursor" (or <span style="color: #881280; font-family: monospace; font-size: 13px;"><character_list<span> <span>cursor="<span>BasicCursor" for those using XML), your query did not make use of any indexes.  In this particular instance, that isn't too fatal, but it would be if you asked for more results.

If the query *is* using an index, you will see "cursor": "BtreeCursor _id_"

 

The coin for a character has been removed from the data feed.

 

New top-level attribute added
A new attribute has been added that displays the amount of time (in seconds) that it took to form the response to a query. This is present in all formats.
xml:

Code:

<character_list limit="1" returned="1" <span style="color: #ff0000;">seconds="0.004158">
<character displayname="Kozara (Freeport)" id="2168961825756"/>
</character_list>

json:
{ "character_list": [ { "displayname": "Kozara (Freeport)", "id": 2168961825756 } ], "limit": 1, "returned": 1, <span style="color: #ff0000;">"seconds": 0.0040030479431152344}