gamerDNA Helix API
Beta 1 - 6/1/2009
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
gamerDNA Helix beta can be used without charge. Users must be gamerDNA members.
There is currently no throttling or limits on the volume or frequency of calls. gamerDNA reserves the right to change this.
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 otehr 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>892560005072</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 type="integer">400</Code>
<Message>Bad Request - One of the parameters was missing or out of range. </Message>
<Details>Limit parameter must be between 1 and 1000</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 Members
3.1.1 Activity - Retrieve a member's latest game activity
Find out what a gamerDNA member has been playing. Members/Activity retrieves an array of all of a user's 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:
Request:
http://helix.gamerdna.com/members/activity?id=HelixSample&apikey=<
YOUR API KEY>
Response:
<helix>
<info>
<copyright>Content is copyright(c) gamerDNA 2009. All rights reserved.</copyright>
<description>Returns members activity for single single gamerDNA member. Only publicly available information is returned.</description>
<name>members/activity</name>
<version>1.0</version>
<request-time>Tue, 02 Jun 2009 18:05:34 -0400</request-time>
</info>
<user>
<id>HelixSample</id>
<username>HelixSample</username>
<member-page>http://HelixSample.gamerdna.com</member-page>
<activities type="array">
<activity>
<event-date type="date">2009-05-31</event-date>
<mood>excited</mood>
<description>rock it.</description>
<last-comment-date/>
<comment-count type="integer">0</comment-count>
<title>HelixSample played Gears of War 2 (X360) on 31/MAY/09</title>
</activity>
</activities>
</user>
</helix>
3.1.2 Info - Get basic 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>
<description>
Returns information about a single gamerDNA member. Only publicly available information is returned.
</description>
<name>members/info</name>
<version>2.0</version>
</info>
<user>
<username>a2nt</username>
<posts type="integer">1</posts>
<lastpost>2008-10-09 06:39:00 EST</lastpost>
<member-page>http://a2nt.gamerdna.com</member-page>
<name>a2nt</name>
<lastactivity>2009-05-03 07:48:52 EST</lastactivity>
<lastvisit>2009-05-03 07:48:52 EST</lastvisit>
<fame>
<nextLevelProgress>32% to next level: Veteran</nextLevelProgress>
<fame-level type="integer">4</fame-level>
<nextRank>Veteran</nextRank>
<rank>Warrior</rank>
<levelPercent type="integer">32</levelPercent>
<fame type="integer">1060</fame>
</fame>
<achievements type="array">
<achievement>
<description>
This member has completed four of nine basic pieces of their profile information.
</description>
<displayorder type="integer">7</displayorder>
<title>Has Dotted Their I's</title>
<icon>dottedIs.gif</icon>
<dateAwarded>2008-08-12 11:02:10</dateAwarded>
</achievement>
<achievement>
<description>This member has added ten or more games to his profile.</description>
<displayorder type="integer">10</displayorder>
<title>I've Been There, Done That</title>
<icon>BTDT.gif</icon>
<dateAwarded>2009-04-18 16:14:18</dateAwarded>
</achievement>
...
</achievements>
</user>
<copyright>Content is copyright(c) gamerDNA 2009. All rights reserved.</copyright>
</helix>3.1.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_APIKEYRespone:<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>Thu, 14 May 2009 17:34:33 -0400</request-time>
<copyright>Content is copyright(c) gamerDNA 2009. All rights reserved.</copyright>
</info>
<user>
<username>a2nt</username>
<id>a2nt</id>
<member-page>http://a2nt.gamerdna.com</member-page>
<games type="array">
<game>
<title>Battlefield 2142</title>
<gameicon>/images3/gameasset/Battlefield-2142/icon.png</gameicon>
<publisher>Electronic Arts</publisher>
<id>battlefield-2142</id>
</game>
<game>
<title>Command & Conquer</title>
<gameicon>/images3/gameasset/defaulticon.png</gameicon>
<publisher>Virgin Interactive Entertainment</publisher>
<id>command-conquer-ibm-pc-compatible</id>
</game>
<game>
<title>World of Goo</title>
<gameicon>/images3/gameasset/defaulticon.png</gameicon>
<publisher>Brighter Minds Media, LLC</publisher>
<id>world-of-goo-ibm-pc-compatible</id>
</game>
</games>
</user>
</helix>3.1.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 one of the online gamine networks and see
thier 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:
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>
<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>
</last-presence>
</user>
</helix>
3.1.5 Posts - Retrieve a member's latest posts
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/posts?id=a2nt&apikey=<
YOUR API KEY>
Response:
<helix>
<info>
<name>members/posts</name>
<version>1.0</version>
<copyright>Content is copyright(c) gamerDNA 2009. All rights reserved.</copyright>
<request-time>Tue, 02 Jun 2009 18:19:16 -0400</request-time>
<description>Returns members posts for single single gamerDNA member. Only publicly available information is returned.</description>
</info>
<user>
<id>a2nt</id>
<username>a2nt</username>
<member-page>http://a2nt.gamerdna.com</member-page>
<posts type="array">
<post>
<title>Why bumping with bulldozers is a bad thing for a 5 year old</title>
<event-date type="date">2008-08-14</event-date>
<mood>interested</mood>
<description>I'm a command and conquer junkie. A few years back my then 5 yrs old son saw it and wanted it to play. (At this point he only played Reader Rabbit) ..... (remainder removed - read it online.)</description>
<last-comment-date/>
<comment-count type="integer">0</comment-count>
</post>
<post>
<title>Goo is a charming game - Im bored with shooting things - time to build</title>
<event-date type="date">2009-04-23</event-date>
<mood>excited</mood>
<description>I was sucked into world of goo - its fun puzzles. Its constructive. As much fun as shooting aliens, bad guys, zombies can be - sometimes you just have to turn swords into plowshares - or goo.</description>
<last-comment-date/>
<comment-count type="integer">0</comment-count>
</post>
</posts>
</user>
</helix>3.1.6 Reviews - Retrieve a member's latest game reviews
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/presence?id=fattychubs&apikey=<
YOUR API KEY>
Response: <helix>
<info>
<copyright>Content is copyright(c) gamerDNA 2009. All rights reserved.</copyright>
<description>Returns members reviews for single single gamerDNA member. Only publicly available information is returned.</description>
<name>members/reviews</name>
<version>1.0</version>
<request-time>Tue, 02 Jun 2009 18:25:09 -0400</request-time>
</info>
<user>
<id>HelixSample</id>
<username>HelixSample</username>
<member-page>http://HelixSample.gamerdna.com</member-page>
<reviews type="array">
<review>
<rating type="integer">4</rating>
<game-name>Battlefield 2142</game-name>
<mini-review>I like the game. Is it a character flaw that I like to be a sneaky sniper?<mini-review/>
</review>
<review>
<rating type="integer">5</rating>
<game-name>Gears of War 2</game-name>
<mini-review>awesome - nuff said.</mini-review>
</review>
</reviews>
</user>
</helix>3.1.7 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/games/search?on=name&for=ActRaiser&apikey=<INSERT YOUR KEY>
Response:
3.2 Games
3.2.1 also_playing - list of other games users play.
Also_playing returns a list of the games users play in addition to the specified game.
Terms:
- Baseline players - Initial group of users we want to see what they play.
- Also_playing - other games baseline group is playing.
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 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 | Start 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&apikey=<INSERT YOUR KEY>&played_before=2009-01-25&also_played_start=2009-01-01&also_played_before=2009-04-15&limit=3
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> <name>Guild Wars</name> <percent-played>100.00</percent-played> <id>guild-wars</id> </game> <game> <name> World of Warcraft</name> <percent-played>25.81</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.2.2 Attention - Returns games getting the most attention
Returns the games currently getting most attention on gamerDNA.com. 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.
- Attribute: attention-score is a relative rank of how much attention a game received. Highest scoring game for this period always receives 100.
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
|
Example:
Request: http://helix.gamerdna.com/games/attention?apikey=<INSERT YOUR KEY>
Response: <helix>
<info>
<name>games/attention</name>
<description>Returns the games currently getting most attention on gamerDNA.com</description>
<request-time>Thu, 14 May 2009 18:53:07 -0400</request-time>
<version>1.0</version>
<copyright>Content is copyright(c) gamerDNA 2009. All rights reserved.</copyright>
</info>
<games>
<game>
<id>world-of-warcraft-wrath-of-the-lich-king-hybrid-windows-mac</id>
<attention-score type="integer">100</attention-score>
<game-icon>http://www.gamerdna.com/images3/gameasset/defaulticon.png</game-icon>
<name>World of WarCraft: Wrath of the Lich King</name>
<number-players type="integer">11865</number-players>
<genre>Role-playing</genre>
<style>Persistent World Online RPG</style>
<platform>PC-MAC</platform>
<cover-image-url>http://www.gamerdna.com/public/images/xd/covers/drg300/g393/g39323j4twq.jpg</cover-image-url>
</game>
<game>
<id>bloons-tower-defense-3-web-flash</id>
<name>Bloons Tower Defense 3</name>
<platform>WEB</platform>
<attention-score type="integer">78</attention-score>
<game-icon>http://www.gamerdna.com/images3/gameasset/defaulticon.png</game-icon>
<number-players type="integer">15</number-players>
<genre>Unknown</genre>
<style>Unknown</style>
<cover-image-url>http://www.gamerdna.com/public/images/xd/covers/drxx00/xx05/xx05086.jpg</cover-image-url>
</game>
...
<game>
<id>thing-thing-arena-3-web-flash</id>
<name>Thing-Thing Arena 3</name>
<platform>WEB</platform>
<attention-score type="integer">71</attention-score>
<game-icon>http://www.gamerdna.com/images3/gameasset/defaulticon.png</game-icon>
<number-players type="integer">21</number-players>
<genre>Unknown</genre>
<style>Unknown</style>
<cover-image-url>http://www.gamerdna.com/public/images/xd/covers/drxx00/xx05/xx05140.jpg</cover-image-url>
</game>
</games>
</helix>
3.2.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. |
Example:
Request:
http://helix.gamerdna.com/games/info?id=guild-wars&limit=3&apikey=<
YOUR API KEY>Response:
<helix>
<info>
<request-time>Thu, 14 May 2009 18:35:23 -0400</request-time>
<name>games/info</name>
<version>1.0</version>
<copyright>Content is copyright(c) gamerDNA 2009. All rights reserved.</copyright>
<description>Returns information about a single game.</description>
</info>
<game>
<name>Halo 3</name>
<platform>X360</platform>
<id>halo-3</id>
<upc>882224444477</upc>
<vendors>
<vendors type="array">
<vendor>
<short-name>gamefly</short-name>
<url>http://www.gamefly.com/</url>
<name>GameFly</name>
<rent>
<url>http://www.gamefly.com/ads/a.asp?a=gdna001&redir=/products/detail.asp?pid=124695</url>
</rent>
</vendor>
<vendor>
<short-name>amazon</short-name>
<url>http://www.amazon.com</url>
<name>Amazon</name>
<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 type="integer">3699</price-current>
</buy>
</vendor>
</game>
</helix>3.2.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 users that don't play the game. to play than an the average gamerDNA population. What games do players of game X play more often than a typical gamerDNA member? In a sense, this routine cranks up the sensitivity to reduce the effect of some of the stalwart games that the majority of users play.
FIXXXXX See also: the
also_playing call returns other games that users of one game by a strict percentage. Its common for a few very popular games to for many games.
FIXX _ tuned to show meaingful results and reelevent trends. The tuning parm,aters could be changed at any point so it is recomnmedned that this call
not be used for longer-term track or quantitative analysis.
Notes:
- Limits the FIXX - how does platform come into play? Only returns games form the same platform as base game.
- What is recent, Experienced?
- What is Count? Number of uysers or playing activities?
- WHat is percent increase? (Over standard user base?)
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 for which we want to see other games users are likely to play.
|
users
| Optional
| Which users should be included in datamine:
All: - Playing activity from all users is considered.
Engaged: Only include users that are experienced in both Experienced users. FIXXX.
Default: All
|
timeframe
| Optional
| For which timeframe should playing activity be included:
All: - All time - All playing activity is considered.
Recent: Only consider playing activity from the last several months.
Default: All
|
id
| Mandatory | ID of the game. Game IDs are returned from the Game/Search and Game/List calls. |
Example:
Request:
http://helix.gamerdna.com/games/likely_to_play?id=halo-3&limit=3&apikey=<
YOUR API KEY>Response:
Returned Attributes:
- percent-increase - (from example below) percent increase that users of halo-3 are playing the returned games over the general gamerDNA population.
FIXXX - remove count from below and from testcase.
<helix>
<games type="array">
<game>
<count>21865</count>
<percent-increase>26.060116573757</percent-increase>
<name>Halo Wars</name>
<id>halo-wars-xbox-360</id>
</game>
<game>
<count>9920</count>
<percent-increase>24.877966033475</percent-increase>
<name>TimeShift</name>
<platform/>
<id>timeshift-xbox-360</id>
</game>
...
<game>
<count>10824</count>
<percent-increase>24.695743059512</percent-increase>
<name>Turok</name>
<platform/>
<id>turok-xbox-360</id>
</game>
</games>
<info>
<request-time>Tue, 26 May 2009 15:39:19 -0400</request-time>
<name>games/likely_to_play</name>
<version>1.0</version>
<copyright>Content is copyright(c) gamerDNA 2009. All rights reserved.</copyright>
<description>Returns the other games that users playing the specified game are more likely to play than are general gamerDNA population.
</description>
</info>
</helix>3.2.5 Popular playing - Returns games gamerDNA members are playing
Returns an ordered list of the games gamerDNA members are playing. Games is sorted most played to least.
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.2.6 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 - would match any game with guild anywhere in its 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
|
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>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 [your api key]
FOR - MANDATORY [the search query]
ON - 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.
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":
//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
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>
<name>Europa 1400: The Guild</name>
<id>europa-1400-the-guild-ibm-pc-compatible</id>
</game>
<game>
<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";
//for each node, lets write out a row in our table
foreach($results as $node)
{
print "<tr>\n";
print "<td>" . $node->id . "</td>\n";
print "<td>" . $node->name . "</td>\n";
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";
}
//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]
ALSO_PLAYED_BEFORE -OPTIONAL [end timeframe for additional games YYYY-MM-DD format]
LIMIT - 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
AND ALLOW DEFAULTS IN THIS EXAMPLE.
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
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("Failure loading Helix Data");
}
//using the documentation we see the structure of our provided data
//it should be something like this
/*
<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>
<name>Guild Wars</name>
<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>
<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)
{
print "No matching records<br />";
}
else
{
//all is well, lets write the table
//start the table
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>