A Javascript API client for both web and NodeJS that connects to the updated v3 ESPN fantasy football API. Available as an npm package.
- 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 https://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.
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.
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.
-
leagueId
is the id for your league.- Example:
387659
- Example:
-
seasonId
matches the year in which the season was played.- Example:
2018
- Example:
-
matchupPeriod
refers to an entire match-up, including if the match-up lasts multiple weeks (not rare in playoff settings for smaller leagues).- Example:
3
refers to the third matchup in your league.
- Example:
-
scoringPeriod
refers to a single NFL week. Since most matchups are 1 week long, thescoringPeriod
will typically match thematchupPeriod
. However, for multi-week matchups,scoringPeriod
allows one to get information about a specific week in the match-up (useful in multi-week playoff match-up).- Example:
3
refers to the third week of the NFL season. - Note: A
scoringPeriodId
of0
refers to the preseason before any games are played. AscoringPeriodId
of18
refers to the end of the season.
- Example:
-
If both a
matchupPeriod
and ascoringPeriod
are used, thescoringPeriod
takes precedence.
// ES6
import { ... } from 'espn-fantasy-football-api'; // web
import { ... } from 'espn-fantasy-football-api/node'; // node
import { ... } from 'espn-fantasy-football-api/web-dev'; // web development build
import { ... } from 'espn-fantasy-football-api/node-dev'; // node development build
// ES5
const { ... } = require('espn-fantasy-football-api'); // web
const { ... } = require('espn-fantasy-football-api/node'); // node
const { ... } = require('espn-fantasy-football-api/web-dev'); // web development build
const { ... } = require('espn-fantasy-football-api/node-dev'); // node development build
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 Client
instances.
import { Client } from 'espn-fantasy-football-api';
const myClient = new Client({ leagueId: 432132 });
You need two cookies from ESPN: espn_s2
and 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.
const client = new Client({
leagueId: 12345,
espnS2: 'YOUR_ESPN_S2',
SWID: 'YOUR_SWID'
});
/* OR */
const myClient = new Client({ leagueId: 12345 });
myClient.setCookies({ espnS2: 'YOUR_ESPN_S2', SWID: 'YOUR_SWID' });
The following script calculate the best possible lineup each team could have started for a week:
const _ = require('lodash');
const { Client } = require('espn-fantasy-football-api/node');
const myClient = new Client({
leagueId: 12345,
espnS2: 'YOUR_ESPN_S2',
SWID: 'YOUR_SWID'
});
class Psychic {
static filterPosition(boxscorePlayer, position) {
return (
boxscorePlayer.position === position ||
_.includes(boxscorePlayer.player.eligiblePositions, position)
);
}
static handleNonFlexPosition(lineup, position) {
const players = _.filter(lineup, (player) => this.filterPosition(player, position));
const sortedPlayers = _.sortBy(players, ['totalPoints']);
return _.last(sortedPlayers);
}
static analyzeLineup(lineup, score) {
let bestSum = 0;
const bestRoster = [];
let numChanges = 0;
const bestQB = this.handleNonFlexPosition(lineup, 'QB')
bestRoster.push(bestQB.player.fullName);
bestSum += bestQB.totalPoints;
if (bestQB.position === 'Bench') {
numChanges += 1;
}
const bestDefense = this.handleNonFlexPosition(lineup, 'D/ST')
bestRoster.push(bestDefense.player.fullName);
bestSum += bestDefense.totalPoints;
if (bestDefense.position === 'Bench') {
numChanges += 1;
}
const bestKicker = this.handleNonFlexPosition(lineup, 'K')
bestRoster.push(bestKicker.player.fullName);
bestSum += bestKicker.totalPoints;
if (bestKicker.position === 'Bench') {
numChanges += 1;
}
const flexPlayers = _.filter(lineup, (player) => this.filterPosition(player, 'RB') ||
this.filterPosition(player, 'WR') ||
this.filterPosition(player, 'TE')
);
const sortedFlexPlayers = _.sortBy(flexPlayers, ['totalPoints']);
const flexPos = { RB: 2, WR: 2, TE: 1, FLEX: 1 };
while (_.sum(_.values(flexPos)) && !_.isEmpty(sortedFlexPlayers)) {
const player = sortedFlexPlayers.pop();
const acceptPlayer = () => {
bestRoster.push(player.player.fullName);
bestSum += player.totalPoints;
if (player.position === 'Bench') {
numChanges += 1;
}
}
if (flexPos.RB && _.includes(player.player.eligiblePositions, 'RB')) {
acceptPlayer();
flexPos.RB -= 1;
} else if (flexPos.WR && _.includes(player.player.eligiblePositions, 'WR')) {
acceptPlayer();
flexPos.WR -= 1;
} else if (flexPos.TE && _.includes(player.player.eligiblePositions, 'TE')) {
acceptPlayer();
flexPos.TE -= 1;
} else if (flexPos.FLEX) {
acceptPlayer();
flexPos.FLEX -= 1;
}
}
return {
bestSum,
bestRoster,
currentScore: score,
numChanges
};
}
static runForWeek({ seasonId, matchupPeriodId, scoringPeriodId }) {
const bestLineups = {};
return myClient.getBoxscoreForWeek({ seasonId, matchupPeriodId, scoringPeriodId }).then((boxes) => {
_.forEach(boxes, (box) => {
bestLineups[box.awayTeamId] = this.analyzeLineup(box.awayRoster, box.awayScore);
bestLineups[box.homeTeamId] = this.analyzeLineup(box.homeRoster, box.homeScore);
});
return bestLineups;
});
}
}
Psychic.runForWeek({ seasonId: 2019, matchupPeriodId: 4, scoringPeriodId: 4 }).then((result) => {
console.log(result);
return result;
});
axios - Promise based HTTP client.
babel + webpack - Compiles and bundles ES6 and next-gen Javascript to browser-compatible Javascript.
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.
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.
Script | Description |
---|---|
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 | Runs all lint tasks |
lint:js | Ensures code style is correct. |
lint:spelling | Ensures spelling is correct. |
serve:docs | Builds and serves docs. Defaults to port 8080. |
test | Starts a jest test runner with access to all unit tests. Pass --watch to keep jest alive and watching for changes. Pass a string as a file inclusion pattern. |
test:integration | Runs the integration tests. |