ncaaf-api

Unofficial Node client for ESPN's college football data. ESPN serves college football under football/college-football, and this wraps those endpoints with retry/timeout transport and parsers that return clean data.

Part of the espn-api family. The parent is one client for every sport. This one is just college football, in the style of swar/nba_api.

Run it

No dependencies. Node 18+ (built-in fetch).

git clone https://github.com/LeSingh1/ncaaf-api
cd ncaaf-api
node examples/scoreboard.js   # college football games
node examples/gamelog.js      # a real player's clean game log
npm test

Use it

import { scoreboardClean, gamelogClean } from "./src/api.js";

await scoreboardClean({ dates: "20260906" });   // tidy array of games
await gamelogClean("ATHLETE_ID");               // [{ date, opponent, atVs, stats }]

Raw endpoints: scoreboard, teams, team, roster, athlete, athletes, gamelog, splits, news, summary, standings, odds, plays. Parsed helpers that hand back clean data: scoreboardClean, teamsClean, rosterClean, gamelogClean.

Daily data

A scheduled GitHub Action runs once a day, pulls that day's college football games from live ESPN, and commits them to data/latest.json when there are any. Off-season days leave the last snapshot in place, so the file is always the most recent day that actually had games. The same run is a canary: if ESPN changes or breaks an endpoint the job fails, so a red build is the early warning that the client needs a fix. Run it yourself with npm run snapshot:daily.

Transport

12 second timeout, up to 3 retries on 429 and 5xx with backoff and Retry-After. Failures throw an Error whose .status and .url are set, so you can branch on the HTTP status (e.g. skip a 404, back off on a 429).

Honest notes

• Unofficial. ESPN does not document or support these endpoints, so they can change or break without warning. Cache responses and do not hammer it.
• Endpoint map credit: this community gist.

License

MIT.