Halo Reach API demo -- enhanced by JQuery and YQL

The recent launch of the major new video game, Halo: Reach, was a HUGE event. It's been the biggest event this year in the entertainment industry, making $200 million on the first day, and clocking 2,000 man-years of gameplay time in the first week! It's difficult to over-state the importance of Reach. It sets new benchmarks in gaming, interactive entertainment, and the web.

Through the Halo game franchise, Bungie has proclaimed a new era of web-integration for console gaming. Their latest game, Reach, continues that tradition, with the launch of the official Halo Reach API. This exciting new web service API opens-up game data like never before, including stats and content from played games (videos, screenshots, etc) for easy usage. Data from the game can now be surfaced on the web and used, analysed, and presented in creative new ways, like never before. If you're a web developer looking for a cool mash-up opportunity for your next hack-day, look no further!

Halo Reach API demo

In this demo, I'll make a call to the Halo Reach API to get data about video clips from some of my recent games, and use that data to display thumbnail images linking though to web pages where these rendered videos can be viewed online. We could obviously do much more in this demo, e.g. embedding HD video right here on the web page! I may update this demo later, or create other demos, with richer functionality, so watch this space... For the source code behind the demo, just view the source of this page. Enjoy! ;)

Live working demo!

Click here to run the demo

Demo status: Ready!


About the Halo Reach API

Wow! With the launch of Halo Reach the market-leading game studio, Bungie, are opening a public API for Halo game data!

The Halo Reach API is a WCF web service (powered by .NET technology from Microsoft), supports SOAP, and also provides RESTful endpoints with data in JSON or XML format. There's an official Halo Reach API User Group that developers can join on the game studio's community website.

This is seriously exciting stuff for techies. Bungie already leads the way in this field -- Halo has by FAR the best game stats in the industry, with unbelievable detail, as well as screenshots and videos. Halo already offers by FAR the best integrated web experience of any game! I feel a gaming hack-day mashup coming on...

I first noted and applauded the Reach API in a comment on my blog post about the launch of the game. (I was at the premiere in London in the week before the launch.)

Harness the full power of the Halo Reach API, by using YQL

YQL is an extremely powerful way of working with web services. There are two very good reasons to use the Halo Reach API through YQL. Firstly, YQL takes care of caching the data, so you don't need to worry about performance of exceeding the API's strict usage limits. Secondly, YQL makes it easy to hide your API Key, so you can use the API in client-side JavaScript without making your secret personal API key easy to steal.

YQL is probably the best kept secret in the world of web development. YQL has loads of useful features, and allows you to query a web service using nice and readable SQL-like syntax, and set-up new and potentially advanced queries (filters, sorts, joins, etc) that can be accessed on a permament URL. In fact, with YQL you can treat the whole web, even ordinary web pages, as a giant database engine, but that's another story!

Example: a working YQL Query (just 3 lines of code)

The following YQL query gets a list of my rendered videos.

USE "http://www.timacheson.com/SkyDrive/DirectLinkRedirect?pageUrl=http://cid-9115a524920cfd6f.office.live.com/self.aspx/.Public/Dev/YQL/Open%20Data%20Tables/Halo%20Reach%20API/Bungie.Reach.GetPlayerRenderedVideos.xml" AS bungie.reach.videos;

SET identifier="ABCDEFGHIJ1234567890abcdefghiABCDEFGHIJj123=" on bungie.reach.videos;

SELECT * FROM bungie.reach.videos WHERE gamertag="cbjoe" AND iPage=0;

Note: in order to work, his query needs a real API key (called "identifier" in the API). The one in this example (highlighted red) is fake. You can generate your Halo Reach API key in the game settings in your account on Bungie.net (create a new account if you don't have one). You can replace my gamertag ("cbjoe") with your own or any player's gamertag.

This simple 3-line YQL query is probably self-explanatory. The first line "USE ..." configures YQL to recognise the Reach API, and soon this step will not be necessary when my open data table definitions have been adopted by YQL. The second line "SET ..." makes the query use your own API key. The third line "SELECT ..."

*** DEMO 1: Try this query yourself right now in the YQL Console! (you need to replace my API key with yours) ***

*** DEMO 2: Try a working demo in the YQL Console (uses a query alias incorporating my own API key) ***

The YQL Console is a convenient to query a web service or API.

YQL Open Data Tables for the Halo Reach API

I've created open data table definitions for importing Halo Reach API data into YQL, and you're welcome to use them -- they're just XML files. I've contributed these open data tables to the official community data tables, as well as uploading them to public my public SkyDrive.

If you want to try creating your own data tables, you can start by checking the official YQL documentation -- particularly the YQL Open Data Table dev guide, and the Open Data Tables reference document. There's a good a good blog post about creating a new open data table for YQL. There's a good blog post about using YQL Storage to keep private data secret.

05 October 2010

Share the love:

Comments: 7

Add Comment

Nagesh Susarla (06 Oct 10, 18:37)

Nice post, Tim. Excellent use of YQL. By hiding the identifier in storage you can wrap your query with the execute key into your webapps/js.

Tim Acheson (07 Oct 10, 07:04)

Thanks, Nagesh! It's great to have a comment on this from somebody at Yahoo, especially the lead engineer for YQL! I linked to your seminal article on using YQL Storage to keep secret data private, naturally. ;)

You may have noticed that I'm using SkyDrive to host the open data table definitions (XML files) for the Halo Reach API, while I wait for them to be pulled into the main repository of community data tables on GitHub, It's something that anybody can easily do, even if they don't have a website or their own hosting options.

Tom Armitage (07 Oct 10, 10:29)

Of course, be sure that any data you're storing anywhere (I don't fully know the specifics of YQL tables, to be honest) is only stored temporarily. The Stats API terms and conditions makes it clear that You may not retain any copies of API Data obtained through the Bungie.net API. The FAQ also clarifies: As long as you are operating under our Terms of Use, you can temporarily save files and statistics that have been made freely available through our API. Use of the API and any data we provide does not imply ownership or grant you permanent storage rights. (I'd link to these, but you don't allow links in your comments). I'm a bit disappointed in the Stats API. It's not as exciting a data-set as I'd hoped: there's nothing that isn't already presented on bungie.net, and I think a lot of early products with it are literally going to be "taking Bungie.net data and just showing it in a different place". This is nice and all - and I appreciate the rarity of this in the games industry - but it's hardly... exciting. And, of course, the Bungie Pro requirement feels very un-weblike...
Tim Acheson (07 Oct 10, 15:46)

Tom, don't worry, the API terms and conditions do permit caching, and that's the only storage you need: "...you can temporarily save files and statistics that have been made freely available through our API..." In fact, the official documentation expressly reccomends it, in relation to managing the rate limit, stating that "the ideal solution is to utilise caching".

Don't be dissapointed. The API essentially exposes all of the data that exists! If you feel there's a piece of data you wanted that's missing, can you identify what it is? The data is available on the website, though obviously not in such a structured and useful format.

It's actually very exciting! No doubt many people will just present the same data in slightly different ways. But that can have a huge impact!

There was a good discussion on data visualisation at dConstruct 2010, a web design/dev conference I attended just recently. The speaker in that session delivered an excellent presentation on data visualisation, and indeed he has set-up a whole website devoted to the beauty of information! An excellent example is a graph showing which countries have the biggest military. China, followed by the USA, etc. But when you present the same figures in context, e.g. as a proportion of GDP or population size, a very different and very much more insightful story emerges, with the chart topped by North Korea, Israel, and various heavily-armed states in Africa and the Middle East.

WIth this API you can can do some really interesting things that nobody has ever done before, especially with YQL which turns the entire Bungie API into a giant relational database that you can query, join and filter how ever you wish! You can now ask interesting and useful questions (e.g. simply do more experienced players get more kills?), and answer those questions instantly, and present the data in graphically beautiful ways -- and so very, very much more.

I can understand the Bungie Pro requirement, and have no objections. It's cheap, one year costing about the price of a pint of beer here in London! That requirement applies only to developers, not web users. I don't see it as "un web-like". Those who lead the way in web infrastructure, like Amazon (with EC2) or Microsoft (with Azure) do charge for their services. Web infrastructure is not free; on the contrary, with scale it becomes expensive. Bungie's core business is gaming, not data or web content. ;)

As long as you have some basic technical skills, and a basic level of imagination, the Bungie API is a very exciting resource! :)

Great use! Would you be interested in writing up some wiki instructions for users at www.haloreachapi.net?
Tim Acheson (14 Oct 10, 10:21)

Hi Ozmo, yes by all means, I'd be happy to contribute to the official Wiki. It's a useful resource, but yes those article stubs do need expanding and it could use a few more sections and of course some code examples. I've written a nice simple SOAP client for server-side stuff with .NET, and that's available for anyone who wants it, too.

I would be one those who would like it! I need a good reference to work from. Thanks!


  • Twitter
  • LinkedIn
  • Facebook
  • Windows Live / Messenger
  • Xbox Live
  • RSS
  • Email