28 December 2022

Before the start of the 2022 - 2023 NFL season, my friend Jordan and I were chatting about fantasy football. His community, The Aces (formerly The Whitelist), was setting up an inaugural, 168-team Aces Fantasy Football League. The 168 teams were split into 14 conferences, with each conference comprised of 12 teams. With so many conferences & teams, Jordan wanted a way to display information about each conference (e.g., the standings) in a single location so that anyone in any league could see how every other team was doing. As a big fantasy football fan and a bit of a nerd 🤓, I thought it would be fun to figure out how to access this information and display it in a useful manner to solve Jordan’s needs. In a series of posts, I’ll share everything I learned through that process.

The first thing I needed to figure out was how to grab all the juicy fantasy football data. But how do we go about doing that? Copy and paste the data? Some expert-level web scraping?

You sure?

Definitely not! We need to access an API to automate the collection of data. The Aces team hosted their fantasy league on ESPN. Unlike Yahoo’s supported and well-documented Fantasy Sports APIs, ESPN does not offer the same - which was honestly a surprise to learn. ESPN does have an API for fantasy, buuuut it is all undocumented. I needed to use some good, old-fashioned detective work to figure out how ESPN uses its own APIs to power its fantasy football sites.

Enhance

I’ll be the first to admit that reverse engineering APIs isn’t exactly the most straightforward task. But with a little bit of determination (and a whole lot of trial and error), I was able to figure out some basics of the API.

Reverse engineering ESPN

The Basics of ESPN’s Fantasy Football API

Primary Variables

The key to interacting with ESPN’s Fantasy Football API is through two variables.

ESPN League ID

Base URLs

ESPN v3 API has two base URLs.

For the current season use

https://fantasy.espn.com/apis/v3/games/ffl/seasons/<SEASON ID>/segments/0/leagues/<LEAGUE ID>

where <SEASON ID> is the current year and <LEAGUE ID> is the league ID.

For any historical season use

https://fantasy.espn.com/apis/v3/games/ffl/leagueHistory/<LEAGUE ID>?seasonId=<SEASON ID>

where <SEASON ID> is any previous year of the league and <LEAGUE ID>` is the league ID.

If you replace the 2 variables in either of these base URLs and place the resulting URL in a browser, you should get a response formatted in JSON, which should look familiar to software developers.

Important note: To access the data for your league through these APIs, you’ll need to make sure you or your league manager has set the league to public. If you have a private league, you’ll have to send cookies with your request. That is out of the scope of this post.

Views

Using the API’s base URLs will show only some basic info about the league members. Not much substance. To get some meat on the bone, we’ll need to request specific “views” of the data. Various views can be requested based on parameters. Here’s a non-exhaustive list of view parameters that I’ve discovered:

We can request a specific view by appending a view=<PARAMETER NAME> query string to the end of a base URL and replacing <PARAMETER NAME> with one of the named values above. Here’s an example:

https://fantasy.espn.com/apis/v3/games/ffl/seasons/<SEASON ID>/segments/0/leagues/<LEAGUE ID>?view=mSettings

Invoking the league view request will return JSON data that looks similar to this:

{
  "draftDetail": {
    "drafted": true,
    "inProgress": false
  },
  "gameId": 1,
  "id": 123456789,
  "scoringPeriodId": 17,
  "seasonId": 2022,
  "segmentId": 0,
  "settings": {
    "acquisitionSettings": {
      "acquisitionBudget": 100,
      "acquisitionLimit": -1,
      "acquisitionType": "WAIVERS_TRADITIONAL",
      "isUsingAcquisitionBudget": false,
      "matchupAcquisitionLimit": -1.0,
      "matchupLimitPerScoringPeriod": true,
      "minimumBid": 1,
      "waiverHours": 24,
      "waiverOrderReset": true,
      "waiverProcessDays": [
      ...

Neat. Now what?

I’m glad you asked! Using the views of ESPN league data, we now have the means to get all the data needed. With a little bit of creativity and some additional API calls, we can use this data to build whatever fantasy football tools and displays your heart desires. In my next post, I’ll show you how I took this data and turned it into something useful.

— Onyx