The DATA API

This forum describes the access of game data through a series of RESTful calls provided to support access by multiple web sites and applications. This system is a centralized service that collects character information from game servers so that it may be accessed by various applications. These include SOE sites, the LaunchPad, 3rd Party Fan sites and mobile companion apps.

Access to this data is available at census.daybreakgames.com. This is available using HTTP and HTTPS.

All requests to the REST interface follow a pattern. There are different patterns for different types of data.



Game Query

This service allows one to request information directly from SOE regarding the status of a game or game entity (e.g. character, item, spell, etc.).

Game queries use the following pattern:

/[s:serviceID]/[format]/{verb}/{game}/{collection}/[{identifier}][?{queryString}]

Any item within brackets ("[]") are optional and may be ommitted. For instance, if you don't have a serviceID, you can just skip that part of the pattern. If you omit the [format], you get data in jml.

census.daybreakgames.com/json/get/eq2/item/2906185062

...is functionally equivilent (from a query perspective) to...

census.daybreakgames.com/s:serviceID/json/eq2/item/2906185062

Using a serviceID allows SOE to provide more capabilities to sites who use this API. It is not currently required, but isencouraged. Your service must be registered with SOE to use this facility. The first step to getting this done is to become a developer.

A special form of the game query is to query for server status. This is done by using the verb, "status".

/[s:serviceID]/{format}/status/game[/serverName]

This is used to retrieve the current status of the game worlds for the given game. This drives a number of sites such as soe.com/status.

Game Images

Game images are also available through this service. These include images representing characters (paperdolls, headshots) or in-game items or abilities.

Requests for game images follow the pattern:

/[s:serviceID]/img/{game}/{collection}/{itemInCollection}/{category}[/{itemInCategory}]

Each item within a collection can have a number of "attachments" - usually an image, but can be any file. For games that support many attachments, there can also be a category and items within each category. The category and the ID for items within each category is game-specific.

EverQuest II has an category for paperdoll, headshot, housethumb and petpaperdoll. The itemInCategory is used only if there is more than one item in the category. There is only one paperdoll, but there could be multiple housethumb attachments.

The REST interface will return all results that match the attributes provided within the query string. The data returned is in the form of a list containing zero or more items from the collection provided in the URL. When using the XML format, the results will be provided in a parent element. In JSON, the results will be in an array ([]). If no results are found, this container will be empty.

format

The results of a call to the REST interface may be in either the eXtensible Markup Language (xml), JavaScript Object Notation (json) or the yaml2 format. The recommended format is json as it is a very efficient way to access data for most applications.

The acceptable format values are...

• xml
• json
• yaml
• yml (same as "yaml")
• jml ("JSON as HTML"...json data format with formatting to make it more readable)

In order to access data across the domain boundary, one may want to use JSON Padding3 (JSONP). To do this, append a callback attribute to the query string of the request that uses the json format.

/json/get/eq2/item/2906185062?callback=foo

The results from this request will be padded within the function name, foo(), so that they may be evaluated by the requesting web site within the correct domain.


verb

This informs the REST interface about the type of request that is being made. Supported verbs are...

• get - retrieve the objects that match the request criteria
• count - retrieve the number of objects that match the request criteria
• status - retrieve status information (currently used for server status only)

game

At this time, the only supported game value is eq2. Other games will be added at a later time.

collection

Supported collections are dynamic and dependent on the game providing data to the service.

Some objects may be omitted from a collection due to certain policies set by each game team to protect player privacy and/or business requirements. Examples of these policies might include...

• Characters may be marked as private so that they are omitted from searches and rankings
• Items may be hidden until they are "discovered" naturally by a customer

identifier

Each object has a unique identifier, which is used for a direct link to the information about that object. This can be found within the structure by the top-level “id” field. All results will have this identifier, even if all other information is hidden.

There are also identifiers that are used in reference to other collections. For example, consider the following collection information from eq2:

Code:

"appearanceslots": [  {      "item": {        "id": 3098863614      },      "id": 2,      "name": "head"  },  {      "item": {        "id": 2334025620      },      "id": 3,      "name": "chest"  }]

The item.id value is a reference to a particular object within the "item" collection. When presenting this information, one can put a link to another query to the REST interface or to resolve that information within its parent object. For more information on how to do this, see the Query Commands section for c:resolve.


imageType

This specifies the type of image that is to be returned when requesting an "img" format.

When retrieving images from the character collection, the supported values are...

• paperdoll - a full picture of the character
• headshot - a picture of the character of from the neck up (suitable for icons)
• housethumb - a picture of a in-game house as published
• petpaperdoll - a full picture of the character's pet

When retrieving information, one can use the c:attachments Query Command and it will include URLs to the various images directly into the information returned for that object. These URLs will use the Game Image pattern and correct imageType.

 

I guess this is your new project Dan, it looks cool.  I have just been poking around the URLs to see what if anything I could work out about it.

Is there a built in way to find what collections are available to a game?

I saw that character and item worked, I also found spell (unfortunatly the server seems to have died after I found that, curtailing my exploration)

 

We just had a slight production hiccup.  It should be back up now.  I'll put up a post with the list of available collections this afternoon.

-dan

 

How does someone control if their characters data is accessable via the API or not? I ask mostly because I think I was able to find one of my characters but not another.

 

As far as I know, there are two things that affect whether or not your characters will show up in the API:

1. Whether or not you have unchecked the checkbox in game that says Share with EQ2Players
2. Whether or not the character has been logged in, zoned, etc., since the feeds went live.

Apparently, there isn't a good way to do a full export of all the character data for every character.  So the data only gets exported when a character is loaded up onto a game server.

So most likely, the characters you're seeing are the ones that have been played since late October/early November.

 

Dethdlr is correct.

At some point, I would like to provide additional controls on how to control access to information.

-dan

 

Out of curiosity, I decided to try out the privacy settings today from in game.

I logged in my warlock, then loaded up the data from the REST API.

I unchecked the checkbox that says share data with EQ2Players

I then took off several pieces of gear and then zoned.

I waited a minute or so and then loaded up the data from the REST API again.  The gear was no longer shown.

I put the gear back on and zoned.

I waited a minute or so and then loaded up the data from the REST API again.  The gear was back.

This would tend to imply that the checkbox in game isn't doing squat at the moment.  Either that or you have to log out and back in for it to take effect.  If that's the case, the screen should say that. 

Hope that helps.  

 

I have found that {identifier} here seems to be optional, sometimes at least.

If I used something like /xml/get/eq2/character/ most of the time it will return 10 items from that collection (which is useful for figuring out what fields you can get out of it.

It can also be missed off but the {queryString} included to search through items in the collection, for example: /xml/get/eq2/character/?displayname=^{put your characters first name here}

 

Yeah...I need to update that.  If you don't have an identifier, don't forget to include the "?" to begin the Query String.

If you leave this off, it will search for "all" objects, but there is a default limit for searches ([strikethru]I believe it is 100 [/strikethru]it is 25).  You can override this by setting an explicit limit with c:limit.  

Remember - be nice when asking for data from the API.

-dan

 

Unless it's changed recently, it defaults to 25 items.

 

It has now changed - it now defaults to a single item.  This makes it easy (and surprisingly quick) to pull a single result to see the structure of the data.

-dan

 

Hi folks,

How to I acquire a service ID? 

Thank you,

Caine

 

First, you follow the instructions to become flagged as a "Data Developer".

Then send an email to [url="mailto:data-feedback@soe.sony.com">data-feedback@soe.sony.com[/url] requesting a service id with your email address, forum handle, and your requested service id.

I could have sworn that info was posted here somewhere but when I went searching for it, I couldn't find it.

 

Hi all, 

I have written data-feedback@ several times about getting a service id and have had no response yet. Is this still the correct email address? 

Thanks,Chris

 

I have made the request to become a "Data Developer" and also sent a Service ID request to the same e-mail address, which I can only assume is an alias.

I will post here when they either respond, or if I don't get a response and I need to persue other methods to get a Service ID.

Nevermind, someone else from my community has taken care of this, as we've been pushing SOE to give us this access for quite a while.