gamerDNA Helix API
Beta 2 - 8/13/2009



  1. 1. Introduction
    1. 1.1 Privacy
    2. 1.2 Requirements - commercial vs. non-commercial use
  2. 2. Usage - Getting Started
    1. 2.1 Authentication - getting and using your API key
    2. 2.2 Sample call
    3. 2.3 Parameters
    4. 2.4 Error Handling
      1. 2.4.1 Error Syntax
      2. 2.4.2 Helix HTTP Return Codes
  3. 3. API Calls
    1. 3.1 Games
      1. 3.1.1 also_playing - list of other games users play (analysis)
      2. 3.1.2 attention -  Returns games getting the most attention
      3. 3.1.3 info - Information about a single game.
      4. 3.1.4 likely_to_play - Datamine games players are likely to play
      5. 3.1.5 Popular playing -  Returns the games gamerDNA members are playing
      6. 3.1.6 Reviews  - (Deprecated) retrieve a game's latest game reviews
      7. 3.1.7 Search - find games
    2. 3.2 Members
      1. 3.2.1 Activity - Retrieve a member's latest game activity
      2. 3.2.2 Info - Get detailed information about a single member.
      3. 3.2.3 games - Get the list of games from a members DNA profile
      4. 3.2.4 presence - Find out what a member is up to
      5. 3.5.5 Search - Search for a Member by name or other fields.
      6. 3.2.6 set_status - update member's status message.
    3. 3.3 Content related
      1. 3.3.1 Conversations
        1. 3.3.1.1 daily_count - per conversations counts for multiple days
        2. 3.3.1.2 trends - per-game conversation volumes
        3. 3.3.1.3 Recent - get most recent game-related raw conversations (full-text)
      2. 3.3.2 Game_Activity
        1. 3.3.2.1 Create - create a new game_activity
        2. 3.3.2.2 Delete - delete an existing game_activity you created
        3. 3.3.2.3 Search - retrieve game activity - who has been playing what..
        4. 3.3.2.4 Rollup_day - per day game play volumes
        5. 3.3.2.5 Rollup_game - game play volumes for single game
      3. 3.3.3 Game_Posts
        1. 3.3.3.1 Create - create a new post
        2. 3.3.3.2 Delete - delete an existing post you own
        3. 3.3.3.3 Search - retrieve game post
      4. 3.3.4 Game_traits
        1. 3.3.4.1 Search - Retrieve game traits for a user or for a game
      5. 3.3.5 Images
        1. 3.3.5.1 Search - Retrieve latest images for a user and/or game
      6. 3.3.7 Reviews
        1. 3.3.7.1 Search - Retrieve latest reviews for game.
      7. 3.3.9 Warhammer
        1. 3.3.9.1 character - view Warhammer character details
  4. 4. Samples (PHP)
    1. 4.1 Games Search sample
    2. 4.2 Games also_playing sample
  5. 5. Change Log

1. Introduction

gamerDNA's Helix API is a web-service that allows programmatic access to gamerDNA data.

1.1 Privacy

Only publicly available data is accessible through Helix.  That is, this is the same information you would see if you browsed www.gamerDNA.com.    Under no circumstances is personally identifiable data (PII) available unless the gamerDNA member has expressly allowed it.   See gamerDNA's privacy policy


1.2 Requirements - commercial vs. non-commercial use

The gamerDNA Helix API beta can be used without charge for any non-commercial use.  Users must be gamerDNA members.

There is currently no throttling, restrictions of calls or limits on the volume or frequency of API calls.  However, gamerDNA reserves the right to change this at any time.

Commercial or high-volume use requires a gamerDNA developer license.  Please contact gamerDNA sales at sales@gamerdna.com for more information.

2. Usage - Getting Started

Helix calls are simple HTTP GETs with XML/HTTP returns.   All parameters are passed on the URL.   Use your favorite programming language to make the HTTP calls and parse the resulting XML. 

 


Checklist:

1.   Create a gamerDNA account and get your APIKEY.  (see Authentication section below.)

2.   Follow steps for a sample Helix call.   (See Sample Call section below.)

3.   Expand your program to use other HELIX API calls.  (See API calls chapter.)


The Samples Chapter contains a few PHP sample apps that show how to make the calls.   (Please see www.gamerdna.com/helix_samples/ for the latest versions of the samples.)


2.1 Authentication - getting and using your API key

Each Helix API call requires an APIKEY.  Every registered member of GamerDNA receives this key.


To get your key:  - log into gamerDNA.  Go Manage your DNA.   (See Manage button in upper right of member page.) Your APIKEY is at the bottom of the panel.


Open the panel from your profile and copy/paste the code. Please do not share the code with anyone. it isn’t secret, but we like to keep track of how many people are using the API.    Also, if there is any abuse we will disable the apikey.   


If you feel your API is being used by someone else let us know and we will assign you a new key.


2.2 Sample call

Helix calls are simple HTTP request and responses.    (note: Every call requires a valid apikey parameter.)



Typical Request:

 

GET http://helix.gamerdna.com/games/search?for=guild&apikey=<YOUR API KEYXXX>


Typical Response:

Reminder:  XML Child elements can be in any order.   They may be in a different order than what is below.  (Your XML parser won't care.)  

<helix>

  <info>
    <name>games/info</name>
    <version>1.0</version>
    <description>Returns information about a single game.</description>

    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved. </copyright>

    <request-time>Mon, 13 Apr 2009 17:25:13 -0400</request-time>

  </info>

   <game>
     <name>Guild Wars</name>
     <upc>89256600507</upc>
     <publisher>NC Interactive</publisher>
     <id>guild-wars</id>
    </game>
 
</helix>


2.3 Parameters


URL encoded - All parameters must be URL encoded before being sent.  Example - no  spaces or raw % characters in game or member names.

 


2.4 Error Handling

 

2.4.1 Error Syntax

Errors will be return in XML format with the following syntax:

<Helix>
    <error>
        <code>400</code>
        <error_msg>Bad Request - One of the parameters was invalid, missing, or out of range.
        </error_msg>
        <details>Parameter out of range. (limit) must be between (1) and (20)</details>
    </error>

</Helix>


The <Error> tag is only present if an error occurred. 

2.4.2 Helix HTTP Return Codes

Helix uses the standard HTTP return codes.    A 200 means success. Anything else implies some type of error.
Error Code
Meaning
200
200
400
Bad Request - One of the request parameters was missing or out of range. 
401 Not Authorized - Missing or invalid API key
403 User was authorized to use Helix and request was valid, but request was denied. 
404
Not Found - Helix object specified by ID parameter was not found.
500 Service Unavailable - Helix service is intentionally turned off for this period.
50x
Your browser of application environment may return a 50x error (e.g., 503) is there was a problem connecting to the Helix webservice.


3. API Calls

3.1 Games

3.1.1 also_playing - list of other games users play (analysis)

Also_playing returns a list of the games users play in addition to the specified game. 

Terms: 

Usage:

 

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
id
MandatoryID of the baseline game.  Game IDs are returned from the Game/Search and Game/List calls.
played_start
Mandatory
YYYY-MM-DD - First day when users played baseline game.
played_end
Mandatory YYYY-MM-DD - Last day when users played baseline game.
also_played_start
Optional timeframe of when baseline users played additional games.
also_start_end
Optional
End of  timeframe of when baseline users played additional games.
limit
Optional
Max number of games to return.  Can be between 1 and 100.  Defaults to 20.

Example:

Request:
http://helix.gamerdna.com/games/also_playing?id=guild-wars&played_before=2009-01-25&also_played_start=2009-01-01&also_played_before=2009-04-15&limit=3&apikey=<INSERT YOUR KEY>

Response:
  <helix>
    <info>
      <name>games/also_playing</name>
      <version>1.0</version>
      <description>Returns a list of games that users play in addition to a specified game.</description>
    </info>
    <games type="array">
      <game>
   &nbsp;    <name>Guild Wars</name>
        <percent-played>100.00</percent-played>
        <id>guild-wars</id>
      </game>
      &lt;game>
        <name> World of Warcraft</name>
        <percent-played>25.81&lt;/percent-played>
        <id>world-of-warcraft</id>
      </game>
      <game>
        <name>Call of Duty 4: Modern Warfare</name>
        <percent-played>8.37</percent-played>
        <id>call-of-duty-4</id>
      </game>
    </games>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </helix>


3.1.2 attention -  Returns games getting the most attention

Returns the games currently getting most attention on gamerDNA.com. This is a fast-twitch,  ephemeral view of whats getting attention right now.    Sometimes its one of the biggies, some times its a relatively small or unknown casual game. 


Use to find out what gamers are interested in.   See http://www.gamerdna.com/now/  for an example of how its used.     The list is updated every 2 minutes. 

 



Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
limit
Optional
Number of games to return.  Must be between 1 and 100.  Defaults to 10.
attributes
Optional
Controls numbers of attributes that are returned for each game.    Values are MIN, NORMAL.      See description in games/info for details.

Example:


Request:
http://helix.gamerdna.com/games/attention?apikey=<INSERT YOUR KEY>
Response:
Attribute:  attention-score is a relative rank of how much attention a game received.   Highest scoring game for this period always receives 100.  

<helix>
  <info>
    <name>games/attention</name>
    <description>Returns the games currently getting most attention on gamerDNA.com</description>
    <version>1.1</version>
    <request_time>Mon, 27 Jul 2009 16:17:23 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<games>
  <count>10</count>
  <game>
    <id>halo-combat-evolved-macintosh</id>
    <name>Halo: Combat Evolved</name>
    <platform>MAC</platform>
    <attention_score>100</attention_score>
  </game>
  <game>
    <id>splosion-man-xbox-360</id>
    <name>Splosion Man</name>
    <platform>X360</platform>
    <attention_score>50</attention_score>
  </game>
  <game>
    <id>bejeweled-2_1_2</id>
    <name>Bejeweled 2</name>
    <platform>PS3</platform>
    <attention_score>50</attention_score>
  </game>
 
...

</games>
</helix>


3.1.3 info - Information about a single game.

Parameters:
apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
id
Mandatory ID of the game.  Game IDs are returned from the Game/Search and Game/List calls.
attributes
Optional
Controls number of attributes returned.
MIN -
-
id
- name
- platform
NORMAL
- upc
FULL
- genre
- style
- number_players
- vendors - nested data on Buy, play, rent data for games.  Not all games will have this.

Warning:  FULL returns a lot of data.   Min attributes are faster than FULL calls.
Default:  NORMAL



Example below shows
Request:
http://helix.gamerdna.com/games/info?attributes=full&id=halo-3&apikey=<YOUR API KEY>

Response:
<helix>
  <info>
    <name>games/info</name>
    <description>Returns information about a single game.</description>
    <version>1.1</version>
    <request_time>Mon, 27 Jul 2009 16:24:02 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<game>
  <id>halo-3</id>
  <name>Halo 3</name>
  <platform>X360</platform>
  <upc>882224444477</upc>
  <genre>Shooter</genre>
  <style>First-Person Shooter</style>
  <number_players>13862</number_players>
<vendors>
  <count>4</count>
  <vendor>
    <name>Amazon</name>
    <short_name>amazon</short_name>
    <url>http://www.amazon.com</url>
    <buy>
      <url>http://www.amazon.com/Halo-3-Xbox-360/dp/B000FRU0NU%3FSubscriptionId%3D00M80WJXPG5SCZNK02G2%26tag%3Dga06a-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D165953%26creativeASIN%3DB000FRU0NU</url>
      <price_current>3699</price_current>
    </buy>
  </vendor>
  <vendor>
    <name>Best Buy</name>
    <short_name>bestbuy</short_name>
    <url>http://www.bestbuy.com</url>
    <buy>
      <url>http://www.anrdoezrs.net/click-3402376-10474050?url=http%3A%2F%2Fwww.bestbuy.com%2Fsite%2Folspage.jsp%3FskuId%3D7294661%26type%3Dproduct%26id%3D1118841876708%26ci_src%3D11138%26ci_sku%3D7294661</url>
      <price_current>3999</price_current>
    </buy>
  </vendor>
  <vendor>
    <name>Buy.com</name>
    <short_name>buycom</short_name>
    <url>http://www.buy.com</url>
    <buy>
      <url>http://affiliate.buy.com/gateway.aspx?adid=17662&amp;aid=10387780&amp;pid=3387778&amp;sURL=http%3a%2f%2fwww.buy.com%2fprod%2fhalo-3-microsoft-halo-3-complete-product-standard-1-user-xbox-360%2fq%2floc%2f108%2f204321101.html</url>
      <price_current>3723</price_current>
    </buy>
  </vendor>
  <vendor>
    <name>GameFly</name>
    <short_name>gamefly</short_name>
    <url>http://www.gamefly.com/</url>
    <rent>
      <url>http://www.gamefly.com/ads/a.asp?a=gdna001&amp;redir=/products/detail.asp?pid=124695</url>
    </rent>
  </vendor>
</vendors>
</game
>
</helix>

3.1.4 likely_to_play - Datamine games players are likely to play

Returns the games that players of one game are more likely to play than the general gamerDNA population.  This routine decreases the effect that some of the stalwart games that the majority of users play.

See also: also_playing call which returns other games that users of one game are also playing.  They are returned by a strict percentage.  What you will see is that there are a few very popular games that many users are also_playing.

Notes:


Parameters:
apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
id
Mandatory ID of the game.  Game IDs are returned from the Game/Search and Game/List calls.
limit
Optional
Number of records to elements return.  Must be between 1,20.  

Default:  10

Example:
Request:
http://helix.gamerdna.com/games/likely_to_play?id=halo-3&limit=3&apikey=<YOUR API KEY>

Response:

Returned Attributes:

 <helix>
  <info>
    <name>games/likely_to_play</name>
    <description>Returns the other games that users playing the specified game are more likely to play than are general gamerDNA population.</description>
    <version>1.0</version>
    &lt;request_time>Mon, 27 Jul 2009 16:36:26 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<games>
  <count>3</count>
  <game>
    <id>halo-wars-xbox-360</id>
    <name>Halo Wars</name>
    <platform>X360</platform>
    <percent_increase>26.060116573757</percent_increase>
  </game>
  <game>
    <id>timeshift-xbox-360</id>
    <name>TimeShift</name>
    <platform>X360</platform>
    <percent_increase>24.877966033475</percent_increase>
  </game>
  <game>
    <id>turok-xbox-360</id>
    <name>Turok</name>
    <platform>X360</platform>
    <percent_increase>24.695743059512</percent_increase>
  </game>
</games>
</helix>


3.1.5 Popular playing -  Returns the games gamerDNA members are playing

Returns an ordered list of the games gamerDNA members are playing.  Games is sorted most played to least. 


See also: Helix calls game_activity/rollup_day and game_activity/rollup_day


Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345

  • Response Attribute - rank is the zero-based order of popularity. 

Example:


Request:
http://helix.gamerdna.com/games/popular_playing?apikey=<INSERT YOUR KEY>

Response:
 <helix>
   <info>
      <description>Returns the games that gamerDNA members are playing most often.</description>
      <request-time>Thu, 14 May 2009 18:40:22 -0400</request-time>
      <name>games/popular_playing</name>
      <version>1.0</version>
      <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
    </info>
    <games type="array">
      <game>
        <name>World of WarCraft: Wrath of the Lich King</name>
        <rank>0</rank>
      <id>world-of-warcraft-wrath-of-the-lich-king-hybrid-windows-mac</id>
    </game>
    <game>
      <name>Call of Duty: World at War</name>
      <rank>1</rank>
      <id>call-of-duty-world-at-war-xbox-360</id>
    </game>

   ...
   
     <game>
      <name>Fable II</name>
      <platform/>
      <rank>9</rank>
      <id>fable-2</id>
    </game>
   </games>
</helix>


3.1.6 Reviews  - (Deprecated) retrieve a game's latest game reviews

Deprecated.   Instead use the Helix call reviews/search and pass the game_id parameter.

3.1.7 Search - find games

Search for a game by name or other fields.  Use the Search call to find game IDs.


Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
for
Mandatory Search phrase.
on
Optional
Field name to search for.   One of:  Name, ID, UPC.  Defaults to Name.

(Note:  UPC search requires match=EXACT.)
match
Optional Controls how games are matched.  All matches are case-insensitive.
 
  • ANY - ex:  for=guild&on=name&match=any - matches games with guild anywhere in their name.  This would include games such as  Guild-wars and The Guild 2.

  • STARTS: ex: for=guild&on=name&match=starts - matches any game that starts with guild.   This would include Guild-wars (starts with guild), but not  The Guild 2 (doesn't begin with guild)

  • This includes guild-wars would match only games named specifically guild-wars.   note:  there be multiple games returned because of platforms. 

  • EXACT: ex: for=guild-wars&on=name&match=exact - would match only games named specifically guild-wars. Note:  there be multiple games returned because of platforms. 

Default: any
limit
Optional Max number of games to return.  Can be between 1 and 100. Defaults to 20.  Only used if match=any or starts

Example:


Request:
http://helix.gamerdna.com/games/search?on=name&for=ActRaiser&apikey=<INSERT YOUR KEY>
Response:
  <helix>
     
<games type="array">
        <game>
      ActRaiser>ActRaiser </name>
          <platform>WII</platform>
          <id>wiiraiser-wii</id>
        </game>
        <game>
          <name>ActRaiser>ActRaiser</name>
          <platform>MOBILE</platform>
          <id>actraiser>actraiser-mobile</id>
        </game>
       ...
      </games>
      <info>
        <name>games/search</name>
          <version>1.0</version>
         <description>Returns games matching search pattern.</description>
      </info>
  </helix>


3.2 Members

3.2.1 Activity - Retrieve a member's latest game activity

Deprecated.   Use game_activity/search?user_id=XXXX  instead


3.2.2 Info - Get detailed information about a single member.

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
id
Mandatory ID of the member.  Member IDs are returned from the Member/Search call.

Example:

Request:
http://helix.gamerdna.com/members/info?id=a2nt&apikey=<YOUR API KEY>

Response:  
  <helix>
  <info>
    <name>members/info</name>
    <description>Returns basic information about a single gamerDNA member.  Only publicly  available information is returned.</description>
    <version>2.0</version>
    <request_time>Mon, 27 Jul 2009 15:49:41 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<user>
  <id>a2nt</id>
  <username>a2nt</username>
  <member_page>http://a2nt.gamerdna.com</member_page>
  <posts>4</posts>
  <lastvisit>2009-07-27 15:49:41 EST</lastvisit>
  <lastactivity>2009-07-27 15:49:41 EST</lastactivity>
  <lastpost>2009-07-26 18:34:32 EST</lastpost>
  <joindate>2008-01-27 19:52:00 EST</joindate>
  <title>GamerDNA staff</title>
  <status/>
  <avatar_image_url>http://www.gamerdna.com/public/images/global/avatar/no_avatar_128_mark.jpg</avatar_image_url>
  <quick_link>&lt;a href="http://www.guildcafe.com/game/Command-and-Conquer"&gt;Command and Conquer&lt;/a&gt;</quick_link>
  <fame>
    <fame>1160</fame>
    <nextRank>Veteran</nextRank>
    <levelPercent>45</levelPercent>
    <rank>Warrior</rank>
   
<fame_level>4</fame_level>
    <nextLevelProgress>45% to next level: Veteran</nextLevelProgress>
  </fame>
  <characters>
    <count>0</count>
  </characters>
  <achievements>
    <count>6</count>
    <achievement>
      <title>Has Dotted Their I's</title>
      <icon>dottedIs.gif</icon>
      <description>This member has completed four of nine basic pieces of their profile information.</description>
      <displayorder>7</displayorder>
&nbsp;     <dateAwarded>2008-08-12 11:02:10&lt;/dateAwarded>
    </achievement>
    <achievement>
      <title>I've Been There, Done That</title>
      <icon>BTDT.gif</icon>
      <description>This member has added ten or more games to his profile.</description>
      <displayorder>10</displayorder>
      <dateAwarded>2009-04-18 16:14:18</dateAwarded>
    </achievement>
    <achievement>
      <title>Has Crossed Their T's</title>
      <icon>crossedTs.gif</icon>
      <description>This member has completed seven of nine basic pieces of their profile information.</description>
      <displayorder>8</displayorder>
      <dateAwarded>2009-06-17 17:27:57</dateAwarded>
    </achievement>
    <achievement>
      <title>Picture Pager</title>
      <icon>picturepager.gif</icon>
      <description>This member has uploaded five images to gamerDNA</description>
      <displayorder>22</displayorder>
      <dateAwarded>2008-08-28 14:37:28</dateAwarded>
    </achievement>
    <achievement>
      <title>Quiz Master</title>
      <icon>quiz.gif</icon>
      <description>This member has completed three quizzes.</description>
      <displayorder>11</displayorder>
      <dateAwarded>2009-03-10 12:17:48</dateAwarded>
    </achievement>
    <achievement>
      <title>A Member of the Chattering Class</title>
      <icon>chatter.gif</icon>
      <description>This member is part of gamerDNA's Chattering Class with a hundred posts to his credit.</description>
      <displayorder>13</displayorder>
      <dateAwarded>2008-10-09 06:39:18</dateAwarded>
    </achievement>
  </achievements>
</user>
</helix>

3.2.3 games - Get the list of games from a members DNA profile

This includes all games the member has included in their profile.

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
id
Mandatory ID of the member.  Member IDs are returned from the Member/Search calls.

Example:

Request:
http://helix.gamerdna.com/members/games?id=a2nt&apikey=YOUR_APIKEY

Use can use the games/info call to get more information on each game.

Response:
<helix>
  <info>
    <name>members/games</name>
    <description>Returns games played by a single single gamerDNA member.  Only publicly  available information is returned.</description>
    <version>1.0</version>
    <request_time>Mon, 27 Jul 2009 15:52:48 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<user>
  <id>a2nt</id>
  <username>a2nt</username>
  <member_page>http://a2nt.gamerdna.com</member_page>
  <games>
    <count>11</count>
    <game>
      <id>acme-lie-detector-polygraph-scanner</id>
      <name>ACME Lie Detector Polygraph Scanner</name>
      <platform>IPHONE</platform>
    </game>
    <game>
      <id>battlefield-2142</id>
      <name>Battlefield 2142</name>
      <platform>PC</platform>
    </game>
    <game>
      <id>command-conquer-ibm-pc-compatible</id>
      <name>Command &amp; Conquer</name>
      <platform>PC</platform>
    </game>
    <game>
      <id>command-conquer-3-tiberium-wars-ibm-pc-compatible</id>
      <name>Command &amp; Conquer 3: Tiberium Wars</name>
      <platform>PC</platform>
    </game>
    <game>
      <id>guild-wars-factions-ibm-pc-compatible</id>
      <name>Guild Wars: Factions</name>
      <platform>PC</platform>
    </game>
    <game>
      <id>madden-nfl-09-xbox-360</id>
      <name>Madden NFL 09</name>
      <platform>X360</platform>
    </game>
    <game>
      <id>mechcommander-2-ibm-pc-compatible</id>
      <name>MechCommander 2</name>
      <platform>PC</platform>
    </game>
    <game>
      <id>mechwarrior-2-ibm-pc-compatible</id>
      <name>MechWarrior 2</name>
      <platform>PC</platform>
    </game>
    <game>
      <id>tetris-ibm-pc-compatible</id>
      <name>Tetris</name>
      <platform>PC</platform>
    </game>
    <game>
      <id>wii-sports-wii</id>
      <name>Wii Sports</name>
      <platform>WII</platform>
    </game>
    <game>
      <id>world-of-goo-ibm-pc-compatible</id>
      <name>World of Goo</name>
      <platform>PC</platform>
    </game>
  </games>
</user>
</helix>

3.2.4 presence - Find out what a member is up to

Presence is an extremely powerful call.  You can find out what a gamerDNA is doing:  whether they are on one of the online gaming networks, see their last gaming activity.  

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
id
Mandatory ID of the member.  Member IDs are returned from the Member/Search call.

Example:  To see what FattyChubbs is up to run...

Request:
http://helix.gamerdna.com/members/presence?id=fattychubs&apikey=<YOUR API KEY>

Response:  

<?xml version="1.0" encoding="UTF-8"?>
<helix>
    <info>
        <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
        <description>Returns presence information about a single gamerDNA member.</description>
        <request-time>Tue, 02 Jun 2009 17:21:29 -0400</request-time>
        <name>members/presence</name>
        <version>2.0</version>
    </info>
    <user>
        <id>fattychubs</id>
        <username>fattychubs</username>
        <name>fattychubs</name>
        <member-page>http://fattychubs.gamerdna.com</member-page>
        <last-game-activity>
            <event-date type="date">2009-06-01</event-date>
            <last-comment-date/>
            <game-activity-page>http://fattychubs.gamerdna.com/game_activity/fattychubs-played-unreal-tournament-2004-pc-on-2009-06-01</game-activity-page>
            <mood>Happy<mood/>
            <game-id>unreal-tournament-2004-ibm-pc-compatible</game-id>
     &nbsp;      <
description>Had a great game.  We rock. <description/>
            <game-page>http://www.gamerdna.com/game/unreal-tournament-2004-ibm-pc-compatible</game-page>
            <game-name>Unreal Tournament 2004 (PC)</game-name>
            <comment-count type="integer">0</comment-count>
            <title>fattychubs played Unreal Tournament 2004 (PC) on 2009-06-01</title>
        </last-game-activity>
        <last-presence>
            <game-id>unreal-tournament-2004-ibm-pc-compatible</game-id>
            <aka-network>Xfire</aka-network>
            <date type="date">2009-06-02</date>
            <game-name>Unreal Tournament 2004</game-name>
            <online type="integer">1</online>
            <online-status/>
            <game-link>http://www.gamerdna.com/game/unreal-tournament-2004-ibm-pc-compatible</game-link>
   &nbsp;    </last-presence>
    </user>
</helix>

3.5.5 Search - Search for a Member by name or other fields. 

Use the Search call to find Member IDs.


Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
for
Mandatory Search phrase.
on
Optional
Field name to search for.   One of:  Name or ID.  Defaults to Name.
match
Optional Controls how Members are matched.  All matches are case-insensitive.
 
  • ANY - ex:  for=elf&on=name&match=any - would match any Member with elf anywhere in its name. 

  • STARTS: ex: for=elf&on=name&match=starts - matches any Member that starts with guild.   This would include Elf-of-death (starts with elf), but not  The Belford (doesn't begin with elf)

  • EXACT: ex: for=elf&on=name&match=exact - would match only the members named specifically elf.    There can only be one.  

Default: any
limit
Optional Max number of Members to return.  Can be between 1 and 100. Defaults to 20.  Only used if match=any

Example:


Request:
http://helix.gamerdna.com/members/search?limit=3&for=HelixS&apikey=<INSERT YOUR KEY>
Response:
<helix>
  <info>
    <name>members/search</name>
    <description>Returns members matching search pattern.</description>
    <version>1.0</version>
    <request_time>Sun, 14 Jun 2009 15:33:42 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<users>
  <count>1</count>
  <user>
    <id>HelixSample</id>
    <username>HelixSample</username>
    <member_page>http://HelixSample.gamerdna.com</member_page>
  </user>
</users>
</helix>


3.2.6 set_status - update member's status message.

Will update the status for the gamerDNA member based on the APIkey.  

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
status
Mandatory text message to set as the users status

Example: To set your own status run the following.

Request:
http://helix.gamerdna.com/members/set_status?status=Gaming!&apikey=<YOUR API KEY>

Response:  
HTTP 200 response if successful.  ON error see details element of <info>

<?xml version="1.0"?>
<helix>
<info>
<name>members/set_status</name>
<description>Sets the user's current status</description>
<version>1.0</version>
<request_time>Mon, 22 Jun 2009 18:46:12 -0400</request_time>
<copyright>Content is copyright(c) gamerDNA 2009. All rights reserved.</copyright>
<note>Status updated successfully</note>
</info>
</helix>

3.3 Content related

This section lists the Helix calls to fetch, create and analyze user-created content.  This ranges from simple conversations to full game reviews.

3.3.1 Conversations

The Conversations Helix calls provide a means to get gaming relating conversations and statistics.    gamerDNA uses Twitter's own public APIs to capture the tweets and then its own internal tools to process and filter the gaming related tweets.

For other game related user generated content see game_activity, images, game_reviews and game_posts Helix calls.

3.3.1.1 daily_count - per conversations counts for multiple days

Use this call to get conversations counts for a date range

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Optional ID of the game to filter.   If supplied, only statistics for this game is returned.

Default: Return statistics for all games.
since
Optional
Controls first day to be returned. Format=YYYY-MM-DD

Default:   today.    This will give less than 24h results.
through
Optional
Controls last day to be be included.  Format = YYYY-MM-DD

Default:   today.    This will give less than 24h results.

Example:  To get the conversations counts for all games for each day between 2009-07-01 and 2009-07-03
 
Request: 
http://helix.gamerdna.com/conversations/daily_count?since=2009-07-01&through=2009-07-03<YOUR API KEY>

Response:

Note:  all times are UTC timezone.


<helix>
  <info>
    <name>conversations/daily_count</name>
    <description>return number of conversations per game for date range.</description>
    <version>1.0</version>
    <request_time>Mon, 27 Jul 2009 18:44:05 -0000</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<days>
  <count>3</count>
  <day>
    <date>2009-07-01</date>
    <games>
      <count>373</count>
      <game>
        <game_name>World of Warcraft</game_name>
        <game_id>world-of-warcraft</game_id>
        <conversations>2461</conversations>
      </game>
      <game>
        <game_name>The Sims 3</game_name>
        <game_id>the-sims-3</game_id>
        <conversations>1954</conversations>
      </game>
      <game>
        <game_name>Halo 3</game_name>
        <game_id>halo-3</game_id>
        <conversations>791</conversations>
      </game>
      <game>
        <game_name>StarCraft 2</game_name>
        <game_id>starcraft-2</game_id>
        <conversations>746</conversations>
      </game>
      <game>
        <game_name>Second Life</game_name>
        <game_id>second-life</game_id>
        <conversations>673</conversations>
      </game>

....  some elements cut ...

   </games>
  </day>
</days>

</helix>

3.3.1.2 trends - per-game conversation volumes

Use this call to get up-to-the-hour aggregate statistics on which games people are conversing online about the most.   Returns latest statistics for all games unless constrained.

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Optional ID of the game to filter.   If supplied, only statistics for this game is returned.

Default: Return statistics for all games.
sort_by
Optional
Controls how Conversations are ordered.

  • 24H - Last 24 hours.
  • 7D    - Last 7 days.
  • 30D  - Last 30 days.
  • Alltime  - For life of data collection.  (which started early June, 2009.)
     
Default:   24H
limit
Optional
limit the number of records returned, valid values are 1 to 2000, defaults to 2000 (Enough to get all of the games.)

Hint:  If you are only interested in the top 10 games, then set limit=10.

Example:  To get the 3 top games mentioned in game conversations in the previous 7 days.

Request: 
http://helix.gamerdna.com/conversations/trends?sort_by=7d&limit=3&<YOUR API KEY>

Response:

<helix>
  <info>
    <name>conversations/trends</name>
    <description>Returns statistics for game-related conversations.</description>
    <version>1.0</version>
    <request_time>Mon, 27 Jul 2009 17:16:53 -0000</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<conversation_games>
  <count>3</count>
  <cache_refresh_rate>600</cache_refresh_rate>
  <game>
    <game_name>World of Warcraft</game_name>
    <game_id>world-of-warcraft</game_id>
    <last_24h>2424</last_24h>
    <last_7d>24751</last_7d>
    <last_30d>75695</last_30d>
    <
alltime>105879</alltime>
  </game>
  <game>
    <game_name>The Sims 3</game_name>
    <game_id>the-sims-3</game_id>
    <last_24h>1170</last_24h>
    <last_7d>11025</last_7d>
    <last_30d>46905</last_30d>
    <alltime>139931</alltime>
  </game>
  <game>
    <game_name>Wii Sports</game_name>
    <game_id>wii-sports-wii</game_id>
    <last_24h>2228</last_24h>
    <last_7d>7869</last_7d>
    <last_30d>16749</last_30d>
    <alltime>23645</alltime>
  </game>
</conversation_games>
</helix>

3.3.1.3 Recent - get most recent game-related raw conversations (full-text)

This call returns the most recent, raw conversations including screen_name and raw text. 

Note:  the non-commercial license only allows access to the most recent conversations.   Contact gamerDNA of you interested in access to conversations from other time frames.

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Optional ID of the game to filter.   If supplied, only conversations for this game are returned.

Default: Return statistics for all games.
limit
Optional
Limit the number of records returned, valid values are 1 to 2000, defaults to 2000.


Notes
:
  • Caution - the results contain raw, unedited tweets from the original tweeter.  The  text may contain language that you or others find objectionable.  gamerDNA assumes no responsibility for the content of these twitter texts.
  • Timestamps are in UTC timezone.
Performance notes: - understanding underlying caching  
  • Conversations come fast.   This Helix call gets a high volume of requests.
  • To keep this call fast,  Helix caches the most recent conversations.
  • The cache refresh rate is listed in XML itself. (normally every 120 seconds)
  • If you call this routine in a loop, you should include a delay that has the same value as the cache refresh rate.  Calling it any more frequently won't get you more recent data and will make our servers cranky.

Request: 
http://helix.gamerdna.com/conversations/recent?<YOUR API KEY>

Response:

<helix>
    <info>
        <name>conversations/recent</name>
        <description>Returns most recent conversations.</description>
        <version>1.0</version>
        <request_time>Fri, 17 Jul 2009 15:20:27 -0400</request_time>
        <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
    </info>
    <conversations>
        <count>2000</count>
            <cache_refresh_rate>60</cache_refresh_rate>
            <conversation>
                <occurred_at>Fri, 17 Jul 2009 23:19:00 -0000</occurred_at>
                <screen_name>Caateryna</screen_name>
                <profile_image_url>http://s3.amazonaws.com/twitter_production/profile_images/237890935/KITTEN_normal.jpg</profile_image_url>
                <text>@foxx675 wow, thats funny! I wanted to try <a href="/game/mass-effect/" class="game" title="Mass Effect">mass effect</a> but its on 360... &gt;&lt;</text>
                <game_name>Mass Effect</game_name>
                <game_id>mass-effect</game_id>
            </conversation>

    ... remainder removed ...
         

     </conversations>
</helix>



3.3.2 Game_Activity

3.3.2.1 Create - create a new game_activity

A Game_activity is a record of you playing a game.   It could be today, yesterday or anytime in the past. 


Note - each user can only have one game_activity per day for each game.


Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
title
Mandatory Title of the post.  Max chars is 254 chars.
game_id
Mandatory
ID of the game you played.  You can get the IDS from a games/search call.
date
Optional
Date (YYYY-MM-DD) of when post applies.  

Default: current day (EST timezone.)
mood
Optional
How are you feeling about the post?  Possible values are:
excited, happy, interested, neutral, bored, frustrated, angry and sad.

Default: neutral.
body
Optional
Text body of the post.   Max chars is 512K.   Default: blank.

Example:

Request:
http://helix.gamerdna.com/game_activity/create&game_id=halo-3&title=Rocked_Halo-3&date=2009-04-13&mood=happy&apikey=<YOUR API KEY>

Response:
<helix>
  <info>
    <name>game_activity/create</name>
    <description>Create a new activity for the current user</description>
    <version>1.0</version>
    <request_time>Mon, 27 Jul 2009 21:24:22 -0000</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
    <note>Created Activity</note>
  </info>
<activities>
  <count>1</count>
  <activity>
    <title>Rocked_Halo-3</title>
    <event_date>2009-04-13</event_date>
    <by_user_id>HelixTestUser</by_user_id>
    <user_member_page>http://HelixTestUser.gamerdna.com</user_member_page>
    <created_at>Sun, 14 Jun 2009 13:53:24 -0400</created_at>
    <mood>happy</mood>
    <comment_count>0</comment_count>
    <last_comment_date/>
    <body/>
    <created_at>Sun, 14 Jun 2009 13:53:24 -0400</created_at>
    <updated_at>Mon, 27 Jul 2009 17:24:22 -0400</updated_at>
    <game>
      <id>halo-3</id>
      <name>Halo 3</name>
      <platform>X360</platform>
    </game>
    <milestones>
      <count>0</count>
    </milestones>
  </activity>
</activities>
</helix>


3.3.2.2 Delete - delete an existing game_activity you created

Delete a game_activity for a specific data and game


Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Mandatory ID  of the game_activity to delete.   IDs are returned from the search and create calls. 
date
Mandatory
Date (YYYY-MM-DD) of when post applies. Defaults to current day.

Example:

Request:
http://helix.gamerdna.com/game_activity/delete&&date=2009-04-13&game_id=halo-3&apikey=<YOUR API KEY>

Response:
returns HTTP 200 and valid XML body.

3.3.2.3 Search - retrieve game activity - who has been playing what.. 

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Optional ID of the game. If supplied, only game posts from this game will be returned. 

Default: return posts from any game.  
user_id
Optional
ID of user.   If supplied, only records from this user will be returned.

Default: all users
limit
Optional
limit the number of records returned, valid values are 1 to 500, defaults to 20
since
Optional
Date (YYYY-MM-DD) - Retrieve records on or after this date.  Defaults to all dates.
through
Optional
Date (YYYY-MM-DD) - Retrieve records up through this date. Leave blank to have no maximum date and default to all dates.

Example:

Request:
http://helix.gamerdna.com/game_activity/search?user_id=wormy&since=2009-05-31&through=2009-06-01&apikey=<YOUR API KEY>

Response:
<helix>
  <info>
    <name>game_activity/search</name>
    <description>Returns activities.</description>
    <version>1.0</version>
    <request_time>Mon, 27 Jul 2009 21:44:37 -0000</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<activities>
  <count>6</count>
  <activity>
    <title>Wormy played Battlestations: Pacific (X360) on 2009-06-01</title>
    <event_date>2009-06-01</event_date>
    <by_user_id>Wormy</by_user_id>
    <user_member_page>http://Wormy.dev1.com</user_member_page>
    <created_at>Tue, 02 Jun 2009 11:05:35 -0400</created_at>
    <mood>happy</mood>
    <comment_count>0</comment_count>
    <last_comment_date/>
    <body>Had a GREAT mission on the Battle of Midway!</body>
    <created_at>Tue, 02 Jun 2009 11:05:35 -0400</created_at>
    <updated_at>Tue, 02 Jun 2009 17:33:26 -0400</updated_at>
    <game>
      <id>battlestations-pacific-xbox-360</id>
      <name>Battlestations: Pacific</name>
      <platform>X360</platform>
    </game>
    <milestones>
      <count>0</count>
    </milestones>
  </activity>
  <activity>
    <title>Wormy played Castle Crashers  (X360) on 2009-06-01</title>
    <event_date>2009-06-01</event_date>
    <by_user_id>Wormy</by_user_id>
    <user_member_page>http://Wormy.dev1.com</user_member_page>
    <created_at>Tue, 02 Jun 2009 11:05:34 -0400</created_at>
    <mood/>
    <comment_count>0</comment_count>
    <last_comment_date/>
    <body/>
    <created_at>Tue, 02 Jun 2009 11:05:34 -0400</created_at>
    <updated_at>Tue, 02 Jun 2009 11:05:34 -0400</updated_at>
    <game>
      <id>castle-crashers-xbox-360</id>
      <name>Castle Crashers </name>
      <platform>X360</platform>
    </game>
    <milestones>
      <count>0</count>
    </milestones>
  </activity>

  ... some activity elements removed
</activities>
</helix>


3.3.2.4 Rollup_day - per day game play volumes

Returns the numbers of users playing games on a single day.  

Note: The game play data is updated each evening for the previous day.   This means Monday's play data is not available until late Tuesday PM.

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Optional ID of the game to filter.   If supplied, only play volumes for this game is returned.

Default: Return play volumes for all games.
on_day
Optional
Day for which we return data.  (in YYYY-MM-DD format.)

Default:  Most recent day.   See note above. 
sort_by
Optional
Controls how result set is sorted. 

  • 1D  - Prior day
  • 7D  - Prior 7 days.
  • 30d - Prior 30 days
     
Default:   1d
limit
Optional
Limit the number of records returned, valid values are 1 to 60000, defaults to 60000 (Enough to get all of the games. - there is normally about 1000 different games played on any day.)

Usage hint:  If you are only interested in the top 10 games, then set limit=10.

Example:  To get the 3 top games played, sorted by highest numbers of players for past 30 days days.

Request: 
http://helix.gamerdna.com/game_activity/rollup_day?limit=3&on_day=2009-04-13&sort_by=30d&apikey=<YOUR API KEY>

Response:
Notes on elements
  • games/game/play_<1,7,30>d - Total players of this game for the past 1,7 or 30 days.
  • games/game/order_<1,7,30>d - Zero-based order of playing counts.

<helix>
  <info>
    <name>game_activity/rollup_day</name>
    <description>Returns playing counts for all games on single day.</description>
    <version>1.0</version>
    <request_time>Wed, 22 Jul 2009 06:12:55 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<games>
  <count>3</count>
  <cache_refresh_rate>43200</cache_refresh_rate>
  <on_day>2009-04-13</on_day>
  <game>
    <play_1d>813</play_1d>
    <order_1d>0</order_1d>
    <play_7d>5789</play_7d>
    <order_7d>0</order_7d>
    <play_30d>18303</play_30d>
    <order_30d>0</order_30d>
    <game_id>halo-3</game_id>
    <game_name>Halo 3</game_name>
    <game_platform>Xbox 360</game_platform>
  </game>
  <game>
    <play_1d>545</play_1d>
    <order_1d>2</order_1d>
    <play_7d>3743</play_7d>
    <order_7d>2</order_7d>
    <play_30d>18141</play_30d>
    <order_30d>1</order_30d>
    <game_id>call-of-duty-world-at-war-xbox-360</game_id>
    <game_name>Call of Duty: World at War</game_name>
    <game_platform>Xbox 360</game_platform>
  </game>
  <game>
    <play_1d>553</play_1d>
    <order_1d>1</order_1d>
    <play_7d>3753</play_7d>
    <order_7d>1</order_7d>
    <play_30d>14394</play_30d>
    <order_30d>2</order_30d>
    <game_id>call-of-duty-4-modern-warfare-xbox-360</game_id>
    <game_name>Call of Duty 4: Modern Warfare</game_name>
    <game_platform>Xbox 360</game_platform>
  </game>
</games>
</helix>


3.3.2.5 Rollup_game - game play volumes for single game

Returns the numbers of users playing a single game on multiple days.  

Note on most recent data - The game play data is updated each evening for the previous day.  This means Monday's play data is not available until late Tuesday PM.

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Mandatory ID of the game to filter.   If supplied, only play volumes for this game is returned.
through
Optional
Latest day to retrieve.  (YYYY-MM-DD format.)

Default:  See notes on most recent data above.
since
Optional Starting day to retrieve.  (YYYY-MM-DD format.)

Default:  6 days before Through parameter.

Example:  To get the 7 days of game play data for 3 top games played, sorted by highest numbers of players for past 30 days days.

Request: 
http://helix.gamerdna.com/game_activity/rollup_game?game_id=halo-3&since=2009-04-13&through=2009-04-15&apikey=<YOUR API KEY>

Response:
Notes on elements
  • games/game/play_<1,7,30>d - Total players of this game for the past 1,7 or 30 days.
  • games/game/order_<1,7,30>d - Zero-based order of playing counts.

<helix>
  <info>
    <name>game_activity/rollup_game</name>
    <description>Playing counts for a single game on multiple days.</description>
    <version>1.0</version>
 &nbsp;  <request_time>Wed, 22 Jul 2009 14:20:14 -0000</request_time>
 &nbsp;  <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<game>
  <game_id>halo-3</game_id>
  <game_name>Halo 3</game_name>
  <game_platform>X360</game_platform>
</game>
<days>
  <count>3</count>
  <day>
    <date>2009-04-13</date>
    <play_1d>813</play_1d>
    <order_1d>0</order_1d>
    <play_7d>5789</play_7d>
    <order_7d>0</order_7d>
    <play_30d>18303</play_30d>
    <order_30d>0</order_30d>
  </day>
  <day>
    <date>2009-04-14</date>
    <play_1d>727</play_1d>
    <order_1d>0</order_1d>
    <play_7d>5906</play_7d>
    <order_7d>0</order_7d>
    <play_30d>18413</play_30d>
    <order_30d>0</order_30d>
  </day>
  <day>
    <date>2009-04-15</date>
    <play_1d>685</play_1d>
    <order_1d>0</order_1d>
    <play_7d>5992</play_7d>
    <order_7d>0</order_7d>
    <play_30d>18579</play_30d>
    <order_30d>0</order_30d>
  </day>
</days>
</helix>

3.3.3 Game_Posts

3.3.3.1 Create - create a new post

Use this call to create a new Post.  A Post is a user comment. It can be about a game (or multiple games),  but it doesn't have to be.  The post is created for the user specified by the apikey.


Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
title
Mandatory Title of the post.  Max chars is 254 chars.
date
Optional
Date (YYYY-MM-DD) of when post applies.   Defaults to current day.
game_id
Optional ID(s) of the game(s).    Delimit multiple IDs with semicolons (;). You can get the IDs from a games/search call.
mood
Optional
How are you feeling about the post?  Possible values are:
excited, happy, interested, neutral, bored, frustrated, angry and sad.

Default: neutral.
body
Optional
Text body of the post.   Max chars is 512K.

Example:

Request:
http://helix.gamerdna.com/game_posts/create?game_id=halo-3&title=RockedIt&date=2009-04-11&mood-happy&apikey=<YOUR API KEY>

Response:
returns HTTP 200 and valid XML body.

3.3.3.2 Delete - delete an existing post you own

Use this call to delete an existing post that your created. 


Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
id
Mandatory ID  of the post to delete.   IDs are returned from the search and create calls. 

Example:

Request:
http://helix.gamerdna.com/game_posts/delete&id=sample_post_title&apikey=<YOUR API KEY>

Response:
returns HTTP 200 and valid XML body.

3.3.3.3 Search - retrieve game post

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Optional ID of the game. If supplied, only game posts from this game will be returned. 

Default: return posts from any game.  
user_id
Optional
ID of user.   If supplied, only records from this user will be returned.

Default: all users
limit
Optional
limit the number of records returned, valid values are 1 to 500, defaults to 20
since
Optional
Date (YYYY-MM-DD) - Retrieve records on or after this date. Reviews older than the since value will not be included.  Defaults to all dates.
through
Optional
Date (YYYY-MM-DD) - Retrieve records up to and including this date. Leave blank to have no maximum date.  Defaults to all dates.

Example:

Request:
http://helix.gamerdna.com/game_posts/search?limit=2&since=2009-05-01&through=2009-05-02&apikey=<YOUR API KEY>

Response:
<helix>
  <info>
    <name>game_posts/search</name>
    <description>Returns posts.</description>
    <version>1.0</version>
    <request_time>Sun, 14 Jun 2009 15:21:07 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<posts>
  <count>2</count>
  <post>
    <id>it-begins</id>
    <title>It Begins.</title>
    <event_date>2009-05-01</event_date>
    <mood>angry</mood>
    <by_user_id>Imran</by_user_id>
    <user_member_page>http://Imran.gamerdna.com</user_member_page>
    <comment_count>9</comment_count>
    <last_comment_date>Wed, 06 May 2009 15:01:16 -0400</last_comment_date>
    <body>Collin Waid - I have challenged you to a battle.

You may have beaten me once, but that was pure luck and you know it.

I invite all those who wish to watch an epic beatdown happen in front of their eyes to check the link below:

http://www.gamesbyemail.com/Games/Play?381506662

Beware spectators, Collin's defeat may be graphic. </body>
    <created_at>Fri, 01 May 2009 23:50:58 -0400</created_at>
    <updated_at>Wed, 06 May 2009 15:01:16 -0400</updated_at>
<games>
  <count>1</count>
  <game>
    <id>link-4</id>
    <name>Link 4</name>
    <platform>WEB</platform>
  </game>
</games>
  </post>
  <post>
    <id>i-miss-those-stupid-lizard-platforming-characters</id>
    <title>I miss those stupid lizard platforming characters</title>
    <event_date>2009-05-01</event_date>
    <mood>sad</mood>
    <by_user_id>deadgrrl</by_user_id>
    <user_member_page>http://deadgrrl.gamerdna.com</user_member_page>
    <comment_count>0</comment_count>
    <last_comment_date></last_comment_date>
    <body>I miss Gex. And Croc. And the old Spyro (recent games just don't measure up). Maybe I should boot up my old PS1 versions. I dunno. *Sigh*</body>
    <created_at>Fri, 01 May 2009 23:42:58 -0400</created_at>
    <updated_at>Fri, 01 May 2009 23:42:58 -0400</updated_at>
<games>
  <count>3</count>
  <game>
    <id>croc-legend-of-the-gobbos-playstation</id>
    <name>Croc: Legend of the Gobbos</name>
    <platform>PS</platform>
  </game>
  <game>
    <id>gex-64-enter-the-gecko-nintendo-64</id>
    <name>Gex 64: Enter the Gecko</name>
    <platform>N64</platform>
  </game>
  <game>
    <id>spyro-the-dragon-playstation</id>
    <name>Spyro the Dragon</name>
    <platform>PS</platform>
  </game>
</games>
  </post>
</posts>
</helix>

3.3.4 Game_traits

3.3.4.1 Search - Retrieve game traits for a user or for a game

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
One of: game_id or user_id
ID of the game. If supplied, returns all of the traits used for a particular game.
user_id
One of: game_id or user_id. ID of user.  If supplied, returns all of the traits a user has applied to any game.

Note:  You must supply either user_id or game_id.  You cannot supply both.

Example:

Request:
http://helix.gamerdna.com/game_traits/search&user_id=HelixSample&apikey=<YOUR API KEY>

Response:
<helix>
  <info>
    <name>game_traits/search</name>
 &nbsp;  <description>Returns traits.</description>
    <version>1.0</version>
    <request_time>Mon, 27 Jul 2009 22:09:22 -0000</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<game_traits>
  <count>5</count>
  <category>
    <name>The Setting</name>
    <count>2</count>
    <trait>
      <name>Cartoony</name>
      <times_used>1</times_used>
    </trait>
    <trait>
      <name>Futuristic Military Iceage</name>
      <times_used>1</times_used>
    </trait>
  </category>
  <category>
    <name>Playing As</name>
    <count>1</count>
    <trait>
      <name>Sniper</name>
      <times_used>1</times_used>
    </trait>
  </category>
  <category>
    <name>Playing Against</name>
    <count>2</count>
    <trait>
      <name>soldiers</name>
      <times_used>1</times_used>
    </trait>
    <trait>
      <name>Other players</name>
      <times_used>1</times_used>
    </trait>
  </category>
  <category>
    <name>How it's Played</name>
    <count>2</count>
    <trait>
      <name>mechs</name>
      <times_used>1</times_used>
    </trait>
    <trait>
      <name>Customization</name>
      <times_used>1</times_used>
    </trait>
  </category>
  <category>
    <name>General Tone</name>
    <count>2</count>
    <trait>
      <name>humorous</name>
      <times_used>1</times_used>
    </trait>
    <trait>
      <name>team-oriented</name>
      <times_used>1</times_used>
    </trait>
  </category>
</game_traits>
</helix>


3.3.5 Images

3.3.5.1 Create - add a new image to your account

Use this call to create add a new image to your account.    The post is created for the user specified by the apikey. 


This should be done using an HTTP POST.    See Sample Form


Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
image_file Mandatory
full file post.   Encoded as Content-Type multipart/form-data according to RFC2388.  See sample form below.
title
Option Title of the image.  Max chars is 254 chars.
description
Optional Optional description.
show_public
Optional true - if this image should be shown as part of your public filmstrip.
false - if not.

default: true
show_personal Optional
true - if this image should be shown as part of your personal filmstrip.
false - if not.

default: true

Example:

Request:  - Sample HTML form to post image.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <title>Helix:  Image post sample</title>
    </head>
    <body>

        <H1>gamerDNA Helix: Image Post Sample</H1>

        <form enctype="multipart/form-data" action="http://helix.gamerdna.com/images/create" method="POST">
                 APIKEY: <input type="text" size="50" maxlength="60" name="apikey"> <br/>
                 File to upload: <input name="image_file" type="file" /> <br/>
                 (optional) Title:       <input type="text" size="50" maxlength="60" name="title"><br/>
                 (optional) Description: <input type="text" size="50" maxlength="128" name="description"><br/>
                 (optional) Game_id:
                 <select name ="game_id">
                            <option selected="yes">none</option>
                            <option>halo-3</option>
                            <option>world-of-warcraft</option>

                 </select>  (Your code pass in any valid game_id.) <br/>
                 Show in public filmstrip:
                   True <input type="radio" name="show_public"  value ="true"  checked="yes" />
                   False <input type="radio" name="show_public" value ="false"  /> <br/>
                    
                 Show in private filmstrip:
                    True <input type="radio" name="show_private"  value="true" checked="yes" />
                    False <input type="radio" name="show_private" value ="false"  /><br/>
              <input type="submit" value="Upload Image" />
        </form>
    </body>
</html>


Response:
returns HTTP 200 and valid XML body.   Full Image info is returned in same format as images/search.
<helix>
  <info>
    <name>images/create</name>
    <description>Post an image.</description>
    <version>1.0</version>
    <request_time>Tue, 11 Aug 2009 13:52:35 -0000</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
    <note>Image created successfully.</note>
  </info>
<image>
  <image>Orb_HalfRes_v01.png</image>
  <id>orb_halfres_v01-png</id>
  <title>Orb_HalfRes_v01.png</title>
  <description>Image of  gDNA logo - half orb style</description>
  <average_rating>0</average_rating>
  <image_mime_type>regular file</image_mime_type>
  <image_filesize>686385</image_filesize>
  <image_height>1407</image_height>
  <image_width>1500</image_width>
  <image_link_page><a target='_blank' href='http://www.gamerdna.com/user_images/show/148204'>Orb_HalfRes_v01.png</a></image_link_page>
  <comment_count>0</comment_count>
  <last_comment_date/>
  <views>0</views>
  <created_at>Tue, 11 Aug 2009 09:52:31 -0400</created_at>
  <updated_at>Tue, 11 Aug 2009 09:52:31 -0400</updated_at>
  <by_user_id>HelixTestUser</by_user_id>
  <by_username>HelixTestUser</by_username>
  <user_member_page>http://HelixTestUser.gamerdna.com</user_member_page>
  <game_id>halo-3</game_id>
  <game_name>Halo 3</game_name>
</image>
</helix>

3.3.5.2 Delete - delete an image from your account

Use this call to delete an existing post that you created. 


Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
id
Mandatory ID  of the image to delete.   IDs are returned from the search and create calls.    See image/id field.

Example:

Request:
http://helix.gamerdna.com/images/delete&id=sample_image_title&apikey=<YOUR API KEY>

Response:
returns HTTP 200 and valid XML body.

3.3.5.3 Search - Retrieve latest images for a user and/or game

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Optional ID of the game. If supplied, only images for this game.  Default: return images from any game.
user_id
Optional
ID of user.   If supplied, only images from this user will be returned.  Default: return images from any user.
limit
Optional
limit the number of records returned, valid values are 1 to 100, defaults to 20

Example:

Request:
http://helix.gamerdna.com/images/search&user_id=a2nt&apikey=<YOUR API KEY>
http://helix.gamerdna.com/images/search?game_id=red-faction-guerrilla-xbox-360&limit=2&apikey=<YOUR API KEY>

Response:
helix>
  <info>
    <name>images/search</name>
    <description>Returns images for users or games.</description>
    <version>1.0</version>
    <request_time>Mon, 27 Jul 2009 18:14:11 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<images>
  <count>2</count>
  <image>
    <image>PropPoster_03.jpg</image>
    <id>propposter_03-jpg-2</id>
    <title>PropPoster_03.jpg</title>
    <description>EDF Propaganda Poster - 3</description>
    <average_rating>0</average_rating>
    <image_mime_type>image/jpeg</image_mime_type>
    <image_filesize>254649</image_filesize>
    <image_height>1024</image_height>
    <image_width>715</image_width>
    <image_link_page>&lt;a target='_blank' href='http://www.gamerdna.com/rails/user_images/show/155862'&gt;PropPoster_03.jpg&lt;/a&gt;</image_link_page>
    <comment_count>0</comment_count>
    <last_comment_date/>
    <views>3</views>
    <created_at>Sat, 11 Jul 2009 19:43:01 -0400</created_at>
    <updated_at>Sat, 11 Jul 2009 19:43:30 -0400</updated_at>
    <by_user_id>WhiteDiabl0</by_user_id>
    <by_username>WhiteDiabl0</by_username>
    <user_member_page>http://WhiteDiabl0.gamerdna.com</user_member_page>
    <game_id>red-faction-guerrilla-xbox-360</game_id>
    <game_name>Red Faction: Guerrilla</game_name>
  </image>
  <image>
    <image>PropPoster_02.jpg</image>
    <id>propposter_02-jpg-2</id>
    <title>PropPoster_02.jpg</title>
    <description>EDF Propaganda - 2</description>
    <average_rating>0</average_rating>
    <image_mime_type>image/jpeg</image_mime_type>
    <image_filesize>301589</image_filesize>
    <image_height>715</image_height>
    <image_width>1024</image_width>
    <image_link_page>&lt;a target='_blank' href='http://www.gamerdna.com/rails/user_images/show/155861'&gt;PropPoster_02.jpg&lt;/a&gt;</image_link_page>
    <comment_count>0</comment_count>
    <last_comment_date/>
    <views>3</views>
    <created_at>Sat, 11 Jul 2009 19:41:55 -0400</created_at>
    <updated_at>Sat, 11 Jul 2009 19:42:38 -0400</updated_at>
    <by_user_id>WhiteDiabl0</by_user_id>
    <by_username>WhiteDiabl0</by_username>
    <user_member_page>http://WhiteDiabl0.gamerdna.com</user_member_page>
    <game_id>red-faction-guerrilla-xbox-360</game_id>
    <game_name>Red Faction: Guerrilla</game_name>
  </image>
</images>
</helix>


3.3.7 Reviews

3.3.7.1 Search - Retrieve latest reviews for game.

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
game_id
Optional ID of the game. If supplied, only reviews from this game will be returned.  Default: return reviews from any game.
user_id
Optional
ID of user.   If supplied, only reviews from this user will be returned.  Default: return reviews from any user.
limit
Optional
limit the number of records returned, valid values are 1 to 500, defaults to 20

Example:

Request:
http://helix.gamerdna.com/reviews/search?game_id=gears-of-war-2&apikey=<YOUR API KEY>
http://helix.gamerdna.com/reviews/search?limit=2&user_id=wormy&apikey=<YOUR API KEY>
Response:
<helix>
  <info>
    <name>reviews/search</name>
    <description>Returns game reviews.</description>
    <version>1.0</version>
    <request_time>Mon, 27 Jul 2009 18:19:25 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<reviews>
  <count>2</count>
  <review>
    <game_id>x-com-ufo-defense-ibm-pc-compatible</game_id>
    <game_name>X-COM: UFO Defense</game_name>
    <created_at>Tue, 02 Jun 2009 00:52:08 -0400</created_at>
    <rating>2</rating>
    <mini_review>I wish I had played this back in the day.  Many folks consider this among their favorite games.  But with no manual, and no idea whats happening, I'm having a hard time with it.</mini_review>
    <by_user_id>Wormy</by_user_id>
    <user_member_page>http://Wormy.gamerdna.com</user_member_page>
  </review>
  <review>
    <game_id>wii-fit-bundle-wii</game_id>
    <game_name>Wii Fit [Bundle]</game_name>
    <created_at>Wed, 27 May 2009 20:55:14 -0400</created_at>
    <rating>3</rating>
    <mini_review>Keeps you fit, and entertained!</mini_review>
    <by_user_id>Wormy</by_user_id>
    <user_member_page>http://Wormy.gamerdna.com</user_member_page>
  </review>
</reviews>
</helix>


3.3.9 Warhammer

3.3.9.1 character - view Warhammer character details

Use this call to get details on a warhammer character.  Provide the name and server, and the current character information will be returned.  Characters must be added via member DNA panel before accessible from API.

Parameters:

apikey
Mandatory
Required for every Helix call.  See Authentication section above to find your own apikey.

An apikey is a 40 char hex string similar to: 12345e03f56b6c1d09f95445ad67fc42edf41345
name
Mandatory the warhammer character name
server
Mandatory the warhammer server name

Example:

Request:
http://helix.gamerdna.com/warhammer/character?name=Nentor&server=Volkmar&apikey=<YOUR API KEY>

Response:
<helix>
  <info>
    <name>warhammer/character</name>
    <description>Returns Warhammer Character Stats</description>
    <version>2.0</version>
    <request_time>Mon, 27 Jul 2009 18:21:33 -0400</request_time>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
  </info>
<character>
  <name>Nentor</name>
  <class>Sorcerer</class>
  <server>Volkmar</server>
  <rank>11</rank>
  <percent_to_next_rank>21</percent_to_next_rank>
  <current_xp>14237</current_xp>
  <next_level_xp>66830</next_level_xp>
  <renown>7</renown>
  <percent_to_next_renown>32</percent_to_next_renown>
  <current_rp>641</current_rp>
  <next_level_rp>2000</next_level_rp>
  <guild>House of gamerDNA</guild>
  <cached>Mon, 27 Jul 2009 18:21:33 -0400</cached>
</character>
</helix>

4. Samples (PHP)

Run the latest  versions of the samples from: http://www.gamerdna.com/helix_samples/

4.1 Games Search sample



<?
/*
    THIS IS A SAMPLE USAGE OF THE GAMERDNA HELIX SEARCH API.  THERE ARE A NUMBER OF WAYS THAT DATA CAN BE PULLED AND USED,
    HOPEFULLY THIS SAMPLE CAN ASSIST YOU IN GETTING STARTED WORKING WITH THE DATA PROVIDED ON THE GAMERDNA HELIX.
        
    USING THE HELIX DOCUMENTATION WE KNOW THAT THIS API HAS THE FOLLOWING PARAMETERS AVAILABLE
    
        APIKEY     - MANDATORY  &nbsp;  [your api key]
        FOR         - MANDATORY     [the search query]
        ON   &nbsp;     - OPTIONAL     [the field to search on - defaults to name]
        MATCH     - OPTIONAL    [any, starts, exact - defaults to any]
        LIMIT     - OPTIONAL    [1 to 100, defaults to 20 only used when MATCH is any]
        
    SEEING THIS WE ARE REQUIRED TO GIVE AN APIKEY, AND THE "FOR" PARAMETER TO INDICATE WHAT WE ARE SEARCHING FOR.  THE OTHER OPTIONAL FIELDS,
    WILL BE EXCLUDING AND ALLOW DEFAULTS IN THIS EXAMPLE.
    
 &nbsp;  FOR THIS EXAMPLE WE ARE GOING TO HARD CODE THE SEARCH TO SHOW GAMES WITH "GUILD" IN THE NAME, AND AS DOCUMENTED IT WILL BE AN "ANY" SEARCH BY DEFAULT
*/
?>

<html>
<head>
<title>Helix Search Sample</title>
</head>
<body>
<?php
//create a variable for API key to reuse when needed
$APIKEY "066d0e6d3fbbe602b175a19a8cdbc6c3c29b3809 ";
$search_string "guild";
try
{
//there are a number of ways to pull data from a REST API, we are going to leverage the simplexml libraries, but we should make sure everything is configured to allow it
if (ini_get('allow_url_fopen') != 1)
{
    
//allow url fopen is not available, probably will require the use of cURL if its available
    
die("Sorry Allow URL FOPEN is not enabled on this server");
}
elseif (
function_exists(simplexml_load_file) != 1)
{
    
//we also need simplexml to exist - which i believe should be valid as long as we are on PHP5
    
die("Sorry simplexml_load_file is not a function on this server, are you using PHP5?");
    
}
//build the search request we are interested in
$url "http://helix.gamerdna.com/games/search?on=name&for=" $search_string "&apikey=" $APIKEY;

//using simple xml we can load up the xml from the API pretty easily, and in a nice object based package.
$xml = @simplexml_load_file($url);
list(
$httpversion,$httpstatuscode,$httpmessage) = explode(" ",$http_response_header[0], 3); 

//validate Status Code before we bother to work with the data (if any)

switch($httpstatuscode)
{
    case 
"400":
        
//documented as bad request
        
die("Helix reported Error 400 - Bad Request");
        break;
    case 
"401":
  &nbsp;   &nbsp; 
//documented as Not Authorized
&nbsp;       
die("Helix reported Error 401 - Not Authorized");
&nbsp;       break;
    case 
"403":
        
//documented as Forbidden
        
die("Helix reported Error 403 - Forbidden");
        break;
    case 
"404":
        
//documented as Not Found
        
die("Helix reported Error 404 - Not Found");
        break;
    case 
"503":
        
//documented as Not Found
        
die("Helix reported Error 503 - Service Unavailable");
        break;
    case 
"200":
        
//all is well!
        
break;
    default:
        
//none of the documented codes - not sure what it is, but its not a 200 meaning ok code.
        
die("Helix Reported Error Status Code " $httpstatuscode);
}
if (
$xml == null)
{
    die(
"Simple XML Failed to Load XML Object");
}

//using the documentation we see the structure of our provided data
//it should be something like this
/*
<helix>
    <games type="array">
        <game>
 &nbsp;          <name>Europa 1400: The Guild</name>
 &nbsp;          <id>europa-1400-the-guild-ibm-pc-compatible</id>
        </game>
        <game>
  &nbsp;         <name>Guild 2</name>
            <id>guild-2</id>
        </game>        
    </games>
    <info>
        <name>games/search</name>
        <description>Returns games matching search pattern.</description>
        <version>1.0</version>
    </info>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
</helix>
*/
//so lets say we want to write a table of all the results
//we can look at the xpath, and get all the nodes that we want to work with, in this example we are looking for all of the /games/game nodes so we can write out details of these nodes
$results $xml->xpath("games/game");

//check if we have any results, if there are no matches, lets let the user know, rather than show a blank table
if (sizeof($results) <= 0)
{
    print 
"No matching records<br />"
;
}
else
{
    
//all is well, lets write the table

    //start the table
    
print "<h1>gamerDNA helix API Sample:  Search for " $search_string "</h1>\n";
    print 
"<table border=\"1\" width=\"100%\">\n";
    print 
"<tr><td><strong>Game Id</strong></td><td><strong>Game Name</strong></td><td><strong>View GamerDNA Game Page</strong></td><td><strong>Use Helix to Get Info</strong></tr>\n";
   &nbsp;
    
//for each node, lets write out a row in our table
   &nbsp;
foreach($results as $node)
    {
        print 
"<tr>\n";
        print 
"<td>" $node->id "</td>\n";
        print 
"<td>" $node->name "</td>\n";
       &nbsp;print 
"<td><a href=\"http://www.gamerdna.com/game/" $node->id "\">View</a></td>\n";
        print 
"<td><A href=\"info_sample.php?id=" $node->id "\">View</a>\n";
        print 
"</tr>\n";
    }
  &nbsp; 
//close the table
    
print "</table>\n";
}

}
catch(
exception $e)
{
    print 
"An exception has occurred " $e;
}

$xml null;
$results null;

print 
"<h1>Full Source For This Sample</h1>";
//this shows the source of this file
highlight_file('search_sample.php');
?>
</body>
</html>


4.2 Games also_playing sample


 <?
/*
    THIS IS A SAMPLE USAGE OF THE GAMERDNA HELIX ALSO PLAYING API.  THERE ARE A NUMBER OF WAYS THAT DATA CAN BE PULLED AND USED,
    HOPEFULLY THIS SAMPLE CAN ASSIST YOU IN GETTING STARTED WORKING WITH THE DATA PROVIDED ON THE GAMERDNA HELIX.
    
    USING THE HELIX DOCUMENTATION WE KNOW THAT THIS API HAS THE FOLLOWING PARAMETERS AVAILABLE - SEE DOCUMENTATION FOR MORE DETAIL
    
        APIKEY                - MANDATORY         [your api key]
        ID                    -MANDATORY        [game id]    
        PLAYED_START            -MANDATORY        [begining timeframe YYYY-MM-DD format]
        PLAYED_BEFORE            -MANDATORY        [end timeframe YYYY-MM-DD format]
        ALSO_PLAYED_START        -OPTIONAL        [begining timeframe for additional games YYYY-MM-DD format]
&nbsp;       ALSO_PLAYED_BEFORE    -OPTIONAL        [end timeframe for additional games YYYY-MM-DD format]
    &nbsp;   LIMIT          &nbsp;      - OPTIONAL        [1 to 100, defaults to 20]
        
    SEEING THIS WE ARE REQUIRED TO GIVE AN APIKEY, A GAMEID AND A START AND END TIME.  THE OTHER OPTIONAL FIELDS, WILL BE EXCLUDING 
  &nbsp; AND ALLOW DEFAULTS IN THIS EXAMPLE.
    
&nbsp;   FOR THIS EXAMPLE WE ARE GOING TO HARD CODE THE ELEMENTS, YOU COULD HOWEVER OF COURSE PROVIDE A FORM OR SOMEWAY TO DYNAMICALLY CREATE WHAT THE 
    PARAMETER VALUES WOULD BE, ETC
    
    WE ARE GOING TO USE THE FOLLOWING PARAMETERS
    id=guild-wars
    apikey=<INSERT YOUR KEY>
    played_start=2009-01-21
    played_before=2009-01-25
    also_played_start=2009-01-01
    also_played_before=2009-04-15
    
*/
?>

<html>
<head>
<title>Helix Also Playing Sample</title>
</head>
<body>
<?php
//create a variable for API key to reuse when needed
$APIKEY "066d0e6d3fbbe602b175a19a8cdbc6c3c29b3809";
try
{
//there are a number of ways to pull data from a REST API, we are going to leverage the simplexml libraries, but we should make sure everything is configured to allow it
if (ini_get('allow_url_fopen') != 1)
{
    
//allow url fopen is not available, probably will require the use of cURL if its available
    
die("Sorry Allow URL FOPEN is not enabled on this server");
}
elseif (
function_exists(simplexml_load_file) != 1)
{
    
//we also need simplexml to exist - which i believe should be valid as long as we are on PHP5
    
die("Sorry simplexml_load_file is not a function on this server, are you using PHP5?");
    
}
//build the search request we are interested in
$url "http://helix.gamerdna.com/games/also_playing?id=guild-wars&apikey=" $APIKEY "&played_start=2009-01-21&played_before=2009-01-25&also_played_start=2009-01-01&also_played_before=2009-04-15";

//using simple xml we can load up the xml from the API pretty easily, and in a nice object based package.
$xml = @simplexml_load_file($url);
list(
$httpversion,$httpstatuscode,$httpmessage) = explode(" ",$http_response_header[0], 3); 
//validate Status Code before we bother to work with the data (if any)

switch($httpstatuscode)
{
    case 
"400":
        
//documented as bad request
        
die("Helix reported Error 400 - Bad Request");
        break;
    case 
"401":
        
//documented as Not Authorized
        
die("Helix reported Error 401 - Not Authorized");
        break;
    case 
"403":
        
//documented as Forbidden
        
die("Helix reported Error 403 - Forbidden");
        break;
    case 
"404":
        
//documented as Not Found
 &nbsp;      
die("Helix reported Error 404 - Not Found");
        break;
    case 
"503":
        
//documented as Not Found
        
die("Helix reported Error 503 - Service Unavailable");
        break;
    case 
"200":
        
//all is well!
        
break;
    default:
&nbsp;       
//none of the documented codes - not sure what it is, but its not a 200 meaning ok code.
        
die("Helix Reported Error Status Code " $httpstatuscode);
}
if (
$xml == null)
{
    die(
"Failure loading Helix Data");
}

//using the documentation we see the structure of our provided data
//it should be something like this
/*
<helix>
   &nbsp;<info>
        <name>games/also_playing</name>
        <version>1.0</version>
        <description>Returns a list of games that users play in addition to a specified game.</description>
    </info>
    <games type="array">
        <game>
            <name>Guild Wars</name>
       &nbsp;    <gameicon>/images3/gameasset/Guild-Wars/icon.png</gameicon>
            <percent-played>100.00</percent-played>
            <id>guild-wars</id>
        </game>
 
       <game>
            <name>World of Warcraft</name>
            <gameicon>/images3/gameasset/World-of-Warcraft/icon.png</gameicon>
    &nbsp;       <percent-played>12.81</percent-played>
            <id>world-of-warcraft</id>
        </game>
    </games>
    <copyright>Content is copyright(c) gamerDNA 2009.  All rights reserved.</copyright>
</helix>
*/

//so lets say we want to write a table of all the results
//we can look at the xpath, and get all the nodes that we want to work with, in this example we are looking for all of the /games/game nodes so we can write out details of these nodes
$results $xml->xpath("games/game");

//check if we have any results, if there are no matches, lets let the user know, rather than show a blank table
if (sizeof($results) <= 0)
{
&nbsp;   print 
"No matching records<br />";
}
else
{
    
//all is well, lets write the table

    //start the table
 &nbsp;  
print "<h1>gamerDNA helix API Sample: Also Playing</h1>\n";
    print 
"<table border=\"1\" width=\"100%\">\n";
    print 
"<tr><td><strong>Game Name</strong></td><td><strong>Percent Played</strong></td></tr>\n";    
    
//for each node, lets write out a row in our table
    
foreach($results as $node)
    {
        
//one gotcha with simple xml - if the node has a dash (like percent-played) you have to define a variable for it
        //so even though we can just use $node->name for the name, $node->percent-node will not work, you have to extract it into a variable as shown below
        
$percentnode "percent-played";
        print 
"<tr><td>" $node->name "</td><td>" $node->$percentnode "</td></tr>\n";
    }
    
//close the table
    
print "</table>\n";
}

}
catch(
exception $e)
{
    print 
"An exception has occurred " $e;
}

$xml null;
$results null;
print 
"<h1>Full Source For This Sample</h1>";
//this shows the source of this file
highlight_file('alsoplaying_sample.php');
?>
</body>
</html>



5. Change Log


Release
Notes
9/Jun/2009
  1. Permanent order of attributes in all XML docs.  (Previously order was undefined and could change for calls.
  2. Games/reviews and members/reviews have been deprecated and replaced with a single call reviews/search.
  3. Count - All calls that can return an array (users, members, reviews) now return a <count> attribute. 
  4. Replaced hypens ("-") in any name with underscores ("_").   This includes:
  •  "request-time" in every call's <info> block
  • games/also_playing's "percent_played"
  • games/likely_to_play's "percent_increase"
  • games/info/vendors short_name and price_current
 
20/Jul/2009
  1. Conversations/trends, Conversations/recent go in.
  2. heavy use of caching.  Look in XML to see if internal cache hints are present.  
27/Jul/2009
  1. Game_activity/rollup_game, game_activity/rollup_day-  these provide game play stats for 1d, 7d & 30d.
18/Aug/2009
  1. Images/search - image/permalink element has been renamed to image/id