Newts Parading Majestically


    0.16.1 • Public • Published

    ESPN Fantasy Football API

    npm node Blazing Fast

    Build Status Maintainability Test Coverage dependencies Status devDependencies Status Known Vulnerabilities

    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.

    Documentation Reference

    Hosted documentation available at


    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.

    Important Notes

    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

    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

    • leagueId is the id for your league.

      • Example: 387659
    • seasonId matches the year in which the season was played.

      • Example: 2018
    • 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.
    • scoringPeriod refers to a single NFL week. Since most matchups are 1 week long, the scoringPeriod will typically match the matchupPeriod. 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 of 0 refers to the preseason before any games are played. A scoringPeriodId of 18 refers to the end of the season.
    • If both a matchupPeriod and a scoringPeriod are used, the scoringPeriod takes precedence.

    Importing ESPN Fantasy Football API

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

    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 Client instances.

    import { Client } from 'espn-fantasy-football-api';
    const myClient = new Client({ leagueId: 432132 });

    Working with Private Leagues

    You'll need two cookies from ESPN: espn_s2 and SWID. These are found at "Application > Cookies >" in the Chrome DevTools when on

    Note: As specified before, this functionality only works in NodeJS.

    myClient.setCookies({ espnS2: 'YOUR_ESPN_S2', SWID: 'YOUR_SWID' });

    Built With

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

    npm scripts

    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 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 --watch to keep jest alive and watching for changes. Pass a string as a file inclusion pattern.
    test:all Runs the unit tests then the integration tests.
    test:integration Runs the integration tests.
    test:unit Runs the unit tests.


    npm i espn-fantasy-football-api

    DownloadsWeekly Downloads






    Unpacked Size

    1.04 MB

    Total Files


    Last publish


    • mkreiser