Technical Overview

Time to Start Coding

You know code. We know sports. Let's build some cool stuff.
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:


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

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

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

Here are some specific examples of helper API calls:

URIDescription Returns a list of all sports currently supported in the ESPN API Returns references to all leagues currently supported within baseball Returns information for all groups/divisions within MLB
Back to top


Common Results

Most successful API calls will return the following common properties in addition to the specific data included in the payload:

Element Description Availability
timestamp Date string indicating when the data was returned.
resultsOffset Integer index or "page" of results within the entire resultset. 0 indicates the first page. If "resultsCount" is greater than "resultsLimit", you can return additional results by using the offset parameter described previously.
status String description of the request status, typically "success" or "error".
resultsLimit Integer indication of the maximum number of results per page.
resultsCount Integer indication of the total results in the resultset.
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


  <message>Resource not found</message>
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 3 groups

  • Internal (ESPN) - ESPN employees and contractors using the API to build ESPN apps;
  • Strategic Partner - strategic partners working w/ ESPN to include ESPN content in their products/services; 
  • 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. 

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. 

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 -->