ESPN Fantasy Football API
- Supports pulling data from ESPN.
- Private league support (NodeJS version only, see Important Notes).
- Highly documented.
- Built for speed and efficiency with caching support.
- Built for extensibility by using ES6 classes.
Hosted documentation available at http://espn-fantasy-football-api.s3-website.us-east-2.amazonaws.com/.
npm install --save espn-fantasy-football-api
There are four files exported in the package:
web.js- Production file built for web environments (main/default file).
node.js- Production file built for NodeJS environments.
web-dev.js- Same as web, but not minified/obfused to make debugging/developing easier.
node-dev.js- Same as node, but not minified/obfused to make debugging/developing easier.
ESPN Databases and Data Storage
This project simply retrieves data from ESPN and formats the responses in an easy to read and use format. ESPN is still responsible for maintaining and providing the data. Recently, many have noticed league data disappearing from previous years, including in other ESPN fantasy sports. This appears to be a result of ESPN deleting this data. While some data exists before 2017 (as of Feb. 1, 2019), some data (such as boxscores) is not longer available.
ESPN API Changes
Since this project wraps the ESPN API, any breaking changes to the ESPN API will break this project. This occurred in February 2019 when ESPN migrated from their v2 API to a new v3 API (the original version of this project was completed in Janurary 2019). This project has been updated to consume ESPN's v3 API.
Private leagues currently only work with the NodeJS version of this project, due to limitations in setting headers in browsers.
How to use
ESPN API Conventions
leagueIdis the id for your league.
seasonIdmatches the year in which the season was played.
matchupPeriodrefers to an entire match-up, including if the match-up lasts multiple weeks (not rare in playoff settings for smaller leagues).
3refers to the third matchup in your league.
scoringPeriodrefers to a single NFL week. Since most matchups are 1 week long, the
scoringPeriodwill typically match the
matchupPeriod. However, for multi-week matchups,
scoringPeriodallows one to get information about a specific week in the match-up (useful in multi-week playoff match-up).
3refers to the third week of the NFL season.
- Note: A
0refers to the preseason before any games are played. A
18refers to the end of the season.
If both a
scoringPeriodare used, the
Importing ESPN Fantasy Football API
// ES6; // web; // node; // web development build; // node development build// ES5const ... = ; // webconst ... = ; // nodeconst ... = ; // web development buildconst ... = ; // node development build
How to Get Data
Creating a Client
This will allow you to call the various methods on the
Client class to grab data for the passed league. For working with multiple leagues, create multiple
;const myClient = leagueId: 432132 ;
Working with Private Leagues
You'll need two cookies from ESPN:
SWID. These are found at "Application > Cookies > espn.com" in the Chrome DevTools when on espn.com.
Note: As specified before, this functionality only works in NodeJS.
axios - Promise based HTTP client.
eslint - Fast code linting to maintain good style and code patterns.
jest - Powerful and fast testing platform.
jsdoc - Generated code documentation.
lodash - Utility library.
This project uses Semantic Versioning. Until the 1.0.0 version is published, all major changes will be published with a minor version bump.
This project is licensed under LGPL-3.0 (see LICENSE for details). Essentially, don't take this project and close source it.
This is my first time writing OSS and picking a license. Feel free to reach out with questions and/or concerns.
|build||Builds the module.|
|build:docs||Builds the docs.|
|clean||Runs all clean scripts.|
|clean:dist||Removes the dist folder.|
|clean:docs||Removes the docs folder.|
|ci||Runs continuous integration tasks. Currently runs lint, unit and integration tests, and build.|
|lint||Ensures code style is correct.|
|serve:docs||Builds and serves docs. Defaults to port 8080.|
|test||Starts a jest test runner with access to all tests. Pass
|test:all||Runs the unit tests then the integration tests.|
|test:integration||Runs the integration tests.|
|test:unit||Runs the unit tests.|