Technical Overview

Time to Start Coding

You know code. We know sports. Let's build some cool stuff.

Easy as 1-2-3

The ESPN Developer Center is your way to build sports applications the way you want them, using ESPN’s repository of content and data. Getting started is easy when you follow these three simple steps:

  1. Register and request your developer key
  2. Confirm your email address
  3. Start working with our APIs immediately
Quick Navigation

Technical Overview

The APIs have been designed so that they are easy to use. There are, however, a few things you need to know before you start using them.

Response Formats Supported

The ESPN API supports XML and JSON / JSONP response formats. You can choose which format you want to have returned when sending an API request. The ESPN API determines the format by parsing the HTTP Accept header.

The following headers are currently supported:

  • Accept: application/json
  • Accept: text/xml

The server responds with an HTTP Content-Type header containing the same value supplied in your Accept header. If you supply a callback function when requesting a JSON response, the server responds with application/javascript.

Creating an API Request

To make an API request, you’ll need to:

  • Have your developer key handy
  • Know the resource you're looking to retrieve
  • Know the format (i.e. JSON, XML) you want the response to be returned in

Here’s an example of an API request:

URI Format: HTTP GET http://api.espn.com/:version/:resource/:method?apikey=:yourkey

Please note: All APIs are currently offered as a Version 1 (/v1/) release. If/when additional versions are created, the documentation for each API will be updated accordingly.

Optimizing performance with GZIP

One easy way to improve performance of your app is to utilize GZIP compression when requesting data from the ESPN API.

GZIP compression is an easy way to reduce the payload of the API response and improve performance of your app. In some cases it can actually reduce the response size by 90%!

To use GZIP in your app, set the Accept-Encoding header on your API request to 'gzip, deflate' like so:
Accept-Encoding: gzip, deflate

Back to top

General URI Parameters Accepted

Parameter Description Sample Value
apikey String - developer key assigned to your account (Required) yourkey
limit Integer - used to limit the number of results returned 5
offset Integer - used for pagination. 11 (will start with the 11th entry in the response)
_accept String - used when you can not set the Accepted header. The most common case of this would be while making JSONP requests via JavaScript text/xml
Back to top

 

Helper API Calls

Many API calls require a specific sport, organizing body (usually an official league), or division as part of the resource portion of the URL. Use the following helper API calls to identify:

  • Sports that are currently supported in the ESPN API
  • Organizing bodies, or leagues (e.g. MLB) that are supported within a sport (e.g. baseball)
  • Divisions (e.g. AL East) that make up the organizing body

How to get a list of all sports supported in the API

http://api.espn.com/:version/sports?apikey=:yourkey

How to get a list of all organizing bodies within a sport

http://api.espn.com/:version/sports/:sportname?apikey=:yourkey

How to get a list of all groups/divisions in an organizing body

http://api.espn.com/:version/sports/:sportname/:leagueabbrev?apikey=:yourkey

Here are some specific examples of helper API calls:

URIDescription
http://api.espn.com/v1/sports?apikey=:yourkey Returns a list of all sports currently supported in the ESPN API
http://api.espn.com/v1/sports/baseball?apikey=:yourkey Returns references to all leagues currently supported within baseball
http://api.espn.com/v1/sports/baseball/mlb?apikey=:yourkey Returns information for all groups/divisions within MLB
Back to top

 

Error Handling

When an error is encountered, you’ll receive an appropriate HTTP response code (for example 404 for "File Not Found".) You’ll also get details returned to you in the body of the response.

XML Sample Response

<response>
	<status>error</status>

	<code>404</code>
	<message>Resource not found</message>
</response>
										
JSON Sample Response

{
	"status": "error",
	"code": 404,
	"message" "Resource not found"
}
Back to top

 

Common HTTP Response Codes

Status Code Description
200 (OK) Request was successful.
400 (Bad Request) Invalid format for your request. Make sure you're passing in the correct parameters.
401 (Unauthorized) Not authorized to make this request. Check the API documentation to be sure that you have access to the API or portion of the API you're making a request to.
403 (Account Over Rate Limit) You have exceeded the allowable number of API queries for your access level.
404 (Not Found) The requested resource could not be found. Check spelling and review feed docs.
500 (Internal Server Error) Server side error processing request. Please try again later.
504 (Gateway Timeout) Server timed out trying to fulfill your request. Please try again later.
Back to top

 

API Consumer Tiers

ESPN groups consumers of its API into 4 groups--

  • Internal (ESPN) - ESPN employees and contractors using the API to build ESPN apps;
  • Premium Partner - strategic partners working w/ ESPN to include ESPN content in their products/services; 
  • Partner - smaller companies and independent app developers working w/ ESPN to include ESPN content in their products/services; offerings for this tier are currently under development; and
  • Public - independent, pre-approved developers using ESPN content according to our Terms and Conditions.

Upon registering, you’ll automatically be placed in the Public tier. Only an ESPN moderator can upgrade your access to a different tier. If you are interested in becoming a strategic partner, please let us know.

Not all API content and data is available across all access tiers. Charts indicating what is returned in the API (and who it's available to) are located in the documentation for each API. 

Our goal is to make as much sports information as possible available to Partner and Public developers. Our offerings may change over time. Please check the ESPN Developer Center regularly for information on new APIs and enhancements.

Back to top

ESPN Attribution and Branding

All developers using the ESPN API are required to provide attribution according to the ESPN Branding Policy and Guidelines.

Back to top

 

Get Started

Now that the basics have been covered, it's time to start working with our APIs. Take a look at the documentation or try live API calls with the ESPN API Explorer to start using the ESPN API.

Back to top