Parsing ESPN API using Java and Google GSON

David GrayJune 14th, 2013Last Updated: June 14th, 2013

2 241 4 minutes read

For my first post, I’ll explain how to parse the ESPN API. The API documentation can be found at http://developer.espn.com/docs.

Firstly, you’ll need to request an API key, then you can start querying the REST API to retrieve the JSON response. In the following example, I’m going to query simply for all the players in the sport of “Soccer” (dam that Americanism ) that play in the Premier League in England.

From reading the documentation, this is the URL that I need to send requests to (with [apiKey] replaced with the correct value).

http://api.espn.com/v1/sports/soccer/eng.1/athletes?apikey=[apiKey]

Something to bear in mind first of all, there’s an offset value that forces you to make multiple queries if you want more than just the 50 results, this is set with a parameter known as offset. So for instance, to get the results from 51-101 the following query would pull these back. We’ll come back to this later as this can cause some slight issues.

http://api.espn.com/v1/sports/soccer/eng.1/athletes?apikey=[apiKey]&offset=51

Now I’ve got the description out the way, I’ll start the code, it should be noted I’m using GSON to parse the JSON so you’ll need to add the following Maven dependency.

<dependency>
	<groupId>com.google.code.gson</groupId>
	<artifactId>gson</artifactId>
	<version>2.2.2</version>
</dependency>

Once this has been done and you’ve ran the maven:install to get the jars downloaded, you can start querying. The code below is simply required to download the JSON from the ESPN API

  private static String readUrl(final String urlString) throws Exception {
		BufferedReader reader = null;
		try {
			final URL url = new URL(urlString);
			reader = new BufferedReader(new InputStreamReader(url.openStream()));
			final StringBuffer buffer = new StringBuffer();
			int read;
			final char[] chars = new char[1024];
			while ((read = reader.read(chars)) != -1) {
				buffer.append(chars, 0, read);
			}
			return buffer.toString();
		} finally {
			if (reader != null) {
				reader.close();
			}
		}
	}

Now we can start parsing this JSON, because the JSON produced has a lot of redundant data, I decided against parsing it into objects and just queried it raw.

private static JsonArray getAthletesJsonArray(final int offset)
  		throws Exception {
		final String json = readUrl(getUrl(offset));
		final JsonArray sports = getSportsJsonArray(json);
		final JsonElement league = sports.get(0);
		return league.getAsJsonObject().get("leagues").getAsJsonArray().get(0)
				.getAsJsonObject().get("athletes").getAsJsonArray();
	}

	private static JsonArray getSportsJsonArray(final String json) {
		final JsonArray sports = new JsonParser().parse(json).getAsJsonObject()
				.get("sports").getAsJsonArray();
		return sports;
	}

	private static String getUrl(final int offset) {
		return APIURL + APIKEY + "&offset=" + offset;
	}

This will give us a JsonArray of Athletes and the associated data that can be pulled about them. It should be noted as this point, the response here varies based on your API allowance (free, partner, paid etc). I’ll leave the relevant ESPN API page here http://developer.espn.com/docs/athletes#parameters.

Now, as we’ve got the relevant JsonArray we want, we can just loop through it to return the data about each player.

for (int offset = 1; offset < 650; offset = offset + 50) {
  		try {
				final JsonArray athletes = getAthletesJsonArray(offset);
				for (final JsonElement athlete : athletes) {
					System.out.println(athlete.getAsJsonObject()
							.get("fullName"));
				}
				Thread.sleep(100);
			} catch (Exception e) {
				e.printStackTrace();
			}
		}

It should be noted a couple of things that may look odd about this code. Firstly, the reason for the sleep is because the API has a limit of how many times a second you can call it, currently as I write this for free you’re limited to once every 3 seconds. Secondly, the reason it’s in a loop of 650 is to do with the offset I referenced earlier in this post. This means you need to query each 50 players, this seems a little computationally expensive as I’d have thought it’d be easier just to return the 602 players rather than having to do the heavy loading of receiving 12 RESTful calls.

Then, when we put this all together you get the class below, this will loop through every player giving you their first name.

package org.espn.app;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;

import com.google.gson.JsonArray;
import com.google.gson.JsonElement;
import com.google.gson.JsonParser;

/**
 * @author David Gray 
 * 
 * This class is simply an example of how to parse the Json
 *         API for ESPN.
 */
public class EspnParser {

  private static final String APIKEY = "apiKey";
	private static final String APIURL = "http://api.espn.com/v1/sports/soccer/eng.1/athletes?apikey=";

	/**
	 * @param arguments
	 *            for main method.
	 */
	public static void main(final String[] args) {
		for (int offset = 1; offset < 650; offset = offset + 50) {
			try {
				final JsonArray athletes = getAthletesJsonArray(offset);
				for (final JsonElement athlete : athletes) {
					System.out.println(athlete.getAsJsonObject()
							.get("fullName"));
				}
				Thread.sleep(100);
			} catch (Exception e) {
				e.printStackTrace();
			}
		}
	}

	private static JsonArray getAthletesJsonArray(final int offset)
			throws Exception {
		final String json = readUrl(getUrl(offset));
		final JsonArray sports = getSportsJsonArray(json);
		final JsonElement league = sports.get(0);
		return league.getAsJsonObject().get("leagues").getAsJsonArray().get(0)
				.getAsJsonObject().get("athletes").getAsJsonArray();
	}

	private static JsonArray getSportsJsonArray(final String json) {
		final JsonArray sports = new JsonParser().parse(json).getAsJsonObject()
				.get("sports").getAsJsonArray();
		return sports;
	}

	private static String getUrl(final int offset) {
		return APIURL + APIKEY + "&offset=" + offset;
	}

	private static String readUrl(final String urlString) throws Exception {
		BufferedReader reader = null;
		try {
			final URL url = new URL(urlString);
			reader = new BufferedReader(new InputStreamReader(url.openStream()));
			final StringBuffer buffer = new StringBuffer();
			int read;
			final char[] chars = new char[1024];
			while ((read = reader.read(chars)) != -1) {
				buffer.append(chars, 0, read);
			}
			return buffer.toString();
		} finally {
			if (reader != null) {
				reader.close();
			}
		}
	}

}

You can download the full project on github https://github.com/david99world/EspnApiParsingExample

Reference: Parsing ESPN API using Java and Google GSON from our JCG partner David Gray at the Code Mumble blog.