Translating Retrosheet to JSON in Java

Happy Earth Day

Take a look at a sample from a Retrosheet event file:

com,"call was upheld by replay"
sub,dysos001,"Sam Dyson",0,0,1
com,"ej,buehm001,P,scotd901,Coming onto the field (not on roster)"
com,"$Jose Bautista stood at HP admiring his homer"

Now if I hadn’t watched 4 replays of this game already, a lot of this CSV file would be unclear to me. This format is also difficult to use in a web API or mobile app which why I was surprised when I couldn’t easily find a JSON version of the Retrosheet Database.


GitHub Link

Download the repository, and see the file for instructions on how to run the tool. You have to provide the Retrosheet files yourself; just extract them into the JSONRetro/data folder after you download them from

Here’s a sample JSON from a different play in that game:

 "play" : {
     "inning" : 7,
     "team" : 0,
     "batter" : "choos001",
     "count" : {
         "balls" : 1,
         "strikes" : 2
     "pitches" : "FBFB",
     "event" : "OA/UREV.3-H(UR)(E2/TH)(NR)"
 "play" : {
    "inning" : 7,
    "team" : 0,
    "batter" : "choos001",
    "count" : {
        "balls" : 2,
        "strikes" : 2
    "pitches" : "FBFB.FS",
    "event" : "K"

I still haven’t decided on a way to parse “event” and “pitches” but that’s why the tool is open source.

The Java

I made heavy use of Apache Commons libraries to simply iterate the CSVRecords in a CSVParser and build a string that gets written to a .json file. There is a 1:1 mapping of event files to json files and the output is 3 times the size but a single json file is still typically less than 1 megabyte. That means you can easily store a large number of these in memory at one time even on a mobile device.

The tool can probably be made much quicker with some multithreading and maybe by not writing out the StringBuilder to file on every iteration. What it does do is provide 100% compliant JSON as validated by JSONLint in about a minute.


I have MLB Gameday Data, the Lahman Database in JSON, and now a JSON version of Retrosheet. This is the starting point to being able to parse every MLB game down to the pitch level with more recent years including details such as the spin rate of every pitch and a description of every play in both Spanish and English.

Downloading MLB Gameday Data in Java

I have a project that I’m working on that involves downloading an entire season’s worth of MLB Gameday data. These files include per-pitch data for all at bats since 2007, with increasingly detailed information being recorded every season. I’ve written a tool in Java that downloads the pertinent files for my needs.

Here’s a sample from a Rangers @ Jays game from the 2015 ALDS:

The last 3 files are the Pitch F/X data and the first two are used for at-bat and game metadata.

How to do it

If you have Java installed, the quick way is to download this and run it from your terminal or command line. The command takes two parameters: 1) the year to download and 2) the local directory to save the files.

java -jar Downloader.jar 2014 "c:\Users\majorsaber\data"

I think it took about 25 minutes for the 2014 season. The tool will continue where it left off if you have to cancel it during the download but it might leave the 1 currently downloading file corrupted. This could probably be improved by multithreading the download which is why I made the code open source.

[UPDATE: The tool is now multithreaded and can download an entire season in 5 minutes!]

How it works

GitHub Repository

The URL template for a single game’s worth of data is

and this is the contents of that directory. By fetching the DOM for that HTML directory listing and parsing it using jsoup, I get a list of all folders that begin with “gid_”. I can then fetch the 5 files that I need from each game’s directory using apache commons-io’s very useful copyURLToFile method.

That’s it. My next task is to map the batter and pitcher IDs from the Gameday data to that in the Lahman Database and Retrosheet so I can cross reference player stats with at-bat level data.

*bat flip*