A personal project, GamerScoreGoal.com, that I have been working involves tracking Xbox live GamerScore. One of my personal favorite Xbox sites is 360voice.com where your Xbox 360 blogs about your playing habits. 360 voice has an API set including one that returns the GamerScore history for a particular Gamertag.
I ended up building a helper class that calls out the 360voice API and returns objects that can be used in .NET programing. It's simply using the XMLDocument object in .NET and filling in some custom objects that you can consume inside your own program. I'm only using a subset of the 360 voice API calls but I figure this code can help someone else out there and can easily be modified to include the missing API calls.
To understand what we need to do we need to understand the API. 360voice is using a simple REST API. That means that we can request a specific URL and will get back an XML document with the information we want. Then we can process the XML into whatever format we want. In this example I want to transform the XML data into in memory objects that I can use in .Net.
The first API that you'll want to consume is 360voice.gamertag.exists since it checks if the Gamertag you want information on is in the 360voice database. It's also their simplest API and a good place to focus on the basics.
The URL we need to get takes this format:
http://www.360voice.com/api/gamertag-exists.asp?tag=Carsinigin
You replace the Gamertag at the end with the one you want to get. Then you will receive back some XML that looks like this:
The XML tag that we are interested in is <gamertag>. It will be "True" or "False". So our method in our Helper class should also return a Boolean.
I created a class called "API360Voice" and a shared(static) function "GamertagExists" that returns a boolean.
Now we want to grab the actual XML from 360voice and load it into an XMLDocument. First thing we need to do is add the import directive for "System.Xml" to the top of the class and declare an variable to hold the XML Document. Then we can use the XMLDocument.Load(String) method to read the XML from 360voice. We just pass in the URL that we want to load into the XMLDocument and .Net takes care of HTTP request and loading the document for us. You will also want to wrap this in a Try...Catch statement since this includes network access and can throw exceptions if you are not connected to the Internet or 360voice is not accessible.
You'll also notice that I passed the Gamertag string into System.Web.HttpUtility.UrlEncode. This function will clean up any special characters so they are safe to pass as a URL. This really helps when you try to implement some of the API's that require you to pass Game names into them. A few like Rainbow Six Vegas actually have a copy write symbol or registered trademark symbol and UrlEncode will handle that for you.
Now we have the XML document loaded into memory on our system and we need to process it to get the value of the gamertag XML tag. So we use the "GetElementsByTagName" method of XMLDocument and pass in "gamertag" as the tag we want. Since .Net doesn't know about the specific format of the XML document we are working on and XML documents may have more the one tag with the same name we get back a XmlNodeList that we can loop though and process. In this case will will only the enter the loop once. Then we just check the InnerText of the node to see if its "True" or "False".
So the final function looks like this:
Next time I'll work on adding the 360voice.gamertag.profile and 360voice.score.getlist. Where we will create objects that will represent the returned XML.
I'm also plan on writing on how to take all this and create an image that you could use as a forum signature or badge on your blog.
I've created a page on the MSDN Code Gallery that will have the source code for this post. Go to the releases tab and grab API360Voice v0.1
Links:
360Voice API List - http://www.360voice.com/forum/topic.asp?TOPIC_ID=3
Source Code: http://code.msdn.microsoft.com/360voiceAPI