Kyle Boddy Entrepreneur, Hacker, Biomechanics Researcher, Baseball Lover.

Advanced Injury Database: RESTful Web Service Launched

Advanced Injury Database

I've launched a RESTful web interface for my Advanced Baseball Injury Database. A major problem with PITCHf/x and injury databases are that people are building them over and over against on their local (or hosted) servers, and this is a huge amount of overhead for the sabermetric community. The way to properly do this is to have one giant amalgamated database with a few trusted caretakers that deal with the updating/maintenance/feature requests while everyone else accesses the data using RESTful web services.

This makes updating and standardizing a dataset much easier and gives end users a much easier back-end interface into the database.

To access the RESTful service, you must first authenticate with the Advanced Baseball Injury Database over Facebook. (Anti-Facebook users: Get over it. I'm not going to spam your wall or steal your info, and I made this database entirely open for you to use.) You can do that on the Detailed Injuries Service page. This stores a unique key in my database and grants you access to make RESTful requests.

Example of the key

Easy enough. Copy that key down. You will need this going forward.

Making the Request: High-Level Overview

All you have to do to get injury information about ANY player from 2002-2010 is to go to this URL:

http://injurydb.drivelinebaseball.com/index.php/injurydb/injuryservice/eliasid/key

(I've been told that "eliasID" is the wrong term and I'm supposed to use mlbAMID. However, I've already coded it like "eliasid" and that's what I call it in real life, so you'll just have to deal with it if it bothers you.)

For example, if you use Jered Weaver's eliasID (450308) and my key (66- wait a minute, nice try), you get this in your web browser (squashed for easier reading):

Jered Weaver

Looks pretty ridiculous, right? Well, that's JavaScript Object Notation - JSON. You can easily parse that to get this:

Jered Weaver - See!

So, how do you do that? Good question.

Making the Request: Low-Level Overview

If you've read this far, you probably want some code examples. No problem. I am a PHP/CodeIgniter/MySQL kind of guy, so those are the examples I'm going to give to you. However, I'm including both the simple way - file_get_contents() - and the tougher (but more universal) way - cURL. They should be all you need to get going.

Here's how you can use file_get_contents() in PHP to decode the JSON and echo it out to the browser:

function testinjuryservice()
	{
		// point it to Jered Weaver's eliasID and return it to the browser
		$contents = file_get_contents('http://injurydb.drivelinebaseball.com/index.php/injurydb/injuryservice/450308/YOURKEYHERE');

		// decode the json returned from the service
		$info = json_decode($contents);

		// count number of injury movements
		// must cast object into an array to accurately count the number of injuries
		$injuries = count((array)$info);
		$x = 1;

		while ($x <= $injuries)
		{
		      // echo $info->{$x}->{'DateOn'};
		      // you would use the above line to get the "DateOn" value for the xth injury
		      // repeat this with DateOff, injury, injury_type, etc

		      // dump contents of the given injury out
		      print_r($info->{$x});
		      echo '<br />';
		      $x++;
		}
	}

And here's the cURL example:

function testinjuryservice()
	{
		// open cURL
		$ch = curl_init();

		// point it to Jered Weaver's eliasID and return it to the browser
		curl_setopt($ch, CURLOPT_URL,
		'http://injurydb.drivelinebaseball.com/index.php/injurydb/injuryservice/450308/YOURKEYHERE');
		curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

		// assign it to $contents
		$contents = curl_exec ($ch);

		// close cURL
		curl_close ($ch);

		// decode the json returned from the service
		$info = json_decode($contents);

		// count number of injury movements
		// must cast object into an array to accurately count the number of injuries
		$injuries = count((array)$info);
		$x = 1;

		while ($x <= $injuries)
		{
		      // echo $info->{$x}->{'DateOn'};
		      // you would use the above line to get the "DateOn" value for the xth injury
		      // repeat this with DateOff, injury, injury_type, etc

		      // dump contents of the given injury out
		      print_r($info->{$x});
		      echo '<br />';
		      $x++;
		}
	}

VERY IMPORTANT: I start the JSON array at 1, not 0. Don't be a slave to default counting. Humans start at 1 when they count up.

If you screw up the eliasID or your authentication key, you will get this error in the array's first position:

{"1":{"1":"Invalid key or eliasID given."}}

Alternatively, I may have banned you from the service for too many requests, which segues well into the next point: Don't abuse this system. This is not meant for you to spider my entire database by requesting every player's information from eliasID 10 (Kris Benson: fun fact) to eliasID 9999999999. Can't we all get along?

Where Do We Go From Here?

Well, if you like the service, drop me a line - kyle at driveline baseball dot com. I'd love to hear from you, and if you want to collaborate, that's cool too.

You can keep an eye out for my articles at The Hardball Times, where I write about PITCHf/x stuff and exercise science things. Or check out my baseball training company's site, Driveline Baseball.

I plan on developing a RESTful PITCHf/x interface in the future depending on interest, my motivational levels, free time, and how much I think this is going to wreck my bandwidth costs. Ideally a bunch of us pitch in, rent a cheap VPS, and we serve it up to all sabermetricians who are interested in this kind of stuff. We write tutorials and make it open source and grant freedom of information. Is that feasible? Who knows!

Have fun.