@alex-kaffetzakis/espn-api

A TypeScript client for ESPN's public API.

Fork notice: This is a fork of mikelaferriere/espn-api, significantly expanded to cover additional ESPN domains (site, core, web, cdn, now, fantasy) with a shared HTTP client, typed errors, and exhaustive types. Published independently on npm as @alex-kaffetzakis/espn-api.

Install

npm install @alex-kaffetzakis/espn-api

Quick start

import { Scoreboard, Summary, League } from '@alex-kaffetzakis/espn-api'

const scoreboard = await Scoreboard.fetch(League.NFL)
const summary = await Summary.fetch(League.NFL, scoreboard.events[0].id)

Configuring the client

All endpoints share a default HTTP client. You can configure timeouts and retries, or swap in your own Axios instance:

import { setDefaultClient, EspnClient } from '@alex-kaffetzakis/espn-api'

setDefaultClient(new EspnClient({ timeout: 15_000, retries: 3 }))

Bring your own HTTP client

Every endpoint ships a pure URL builder alongside its fetch* helper. Use it when you'd rather hand URLs to your own HTTP client (fetch, got, undici, etc.) instead of the bundled axios transport:

import { LeagueData, BASE_URLS, League } from '@alex-kaffetzakis/espn-api'

const { domain, path } = LeagueData.injuriesUrl(League.NBA)
const data = await myClient.get(`${BASE_URLS[domain]}/${path}`)

URL builders are pure — they take the same arguments as the matching fetch* helper (minus the client) and return { domain, path, params? }. BASE_URLS maps each domain to its base URL.

Every fetch* helper also accepts an optional EspnClient as its last argument, so you can route specific calls through a custom-configured client without replacing the default:

import { Scoreboard, EspnClient, League } from '@alex-kaffetzakis/espn-api'

const custom = new EspnClient({ timeout: 5_000 })
const sb = await Scoreboard.fetch(League.NFL, undefined, custom)

Error handling

import {
  Summary,
  League,
  EspnNotFoundError,
  EspnRateLimitError,
  EspnApiError,
} from '@alex-kaffetzakis/espn-api'

try {
  await Summary.fetch(League.NFL, 'bad-event-id')
} catch (err) {
  if (err instanceof EspnNotFoundError) {
    // 404
  } else if (err instanceof EspnRateLimitError) {
    // 429
  } else if (err instanceof EspnApiError) {
    // other HTTP / network errors
  }
}

Covered APIs

• Site v2 — scoreboard, summary, teams, league, athletes
• Core v2/v3 — events, athletes, metadata, college, bracketology
• Web — search
• CDN — games
• Now — news
• Fantasy — league

See lib/index.ts for the full list of exports.

Development

npm install
npm run build
npm test

Live integration tests (off by default) hit the real ESPN API:

ESPN_INTEGRATION=true npm test

Publishing (maintainer)

Releases are cut manually from a clean working tree.

# 1. Bump the version and CHANGELOG.md, commit
npm version <patch|minor|major>   # creates the commit + tag

# 2. Log in to npm (once per machine)
npm login

# 3. Publish. prepublishOnly runs lint + tests + build first.
npm publish --access public

# 4. Push the commit and tag
git push && git push --tags

prepublishOnly in package.json runs npm run lint && npm test && npm run build before the publish goes out, so a broken tree won't ship.

License

MIT — see LICENSE.md. Original copyright held by Michael Laferriere; fork modifications by Alex Kaffetzakis.

Disclaimer

Not affiliated with ESPN. This library wraps ESPN's undocumented public endpoints; please use responsibly and respect ESPN's terms of service.