ESPN Scoreboard Scraper

Scores, fixtures and league tables for any date, month or season — NFL, NBA, MLB, NHL, WNBA, college football and basketball, and world football.

HTTP-only. Keyless, no login, no browser.

Why this exists next to a matches scraper

This repo already has sports/sofascore-matches, and its own notes record the gap that this actor fills: SofaScore has no date-based fixture endpoint. Five path shapes were tried there, all 404. A question as ordinary as "what was played on 12 September?" could not be answered.

ESPN answers it, and carries things SofaScore does not: per-period scores, team win-loss records, TV broadcast listings, statistical leaders with named players, attendance, and league tables with qualification zones.

What you get

Field	Example
shortName / name	DET @ BUF / Detroit Lions at Buffalo Bills
startsAt	2026-09-18T00:15Z
statusName / statusDetail / isCompleted	STATUS_FINAL / Final / true
homeTeam / homeScore / homeRecord	Buffalo Bills / 41 / 2-0
awayTeam / awayScore / awayRecord	Detroit Lions / 31 / 1-1
winner	home, away or draw
venue / venueCity / attendance	Highmark Stadium / Orchard Park / 69214
broadcasts	["Prime Video"]
week / seasonYear / seasonType	2 / 2026 / 2

With Include per-period scores: homeLinescores / awayLinescores — [{"period": 1, "value": 14.0}, …], whatever periods the sport has.

With Include statistical leaders: leaders — {"category": "passingYards", "athlete": "Jared Goff", "position": "QB", "jersey": "16", "team": "DET", "display": "26/38, 327 YDS, 4 TD"}.

In standings mode: one row per team with rank, orderInGroup, stats, statLabels, group and note (the qualification zone — Champions League, Relegation, a playoff seed).

The limit will misrepresent a season if you leave it alone

The single most important thing to know about this source. Same league, same query, three limits:

Request	Matches	Dates covered
dates=2026	100	2026-01-03 → 2026-09-20
dates=2026&limit=300	300	2026-01-03 → 2026-12-20
dates=2026&limit=1000	320	2026-01-03 → 2027-01-01

The API's default of 100 does not just drop rows off the end — it changes where the season appears to finish. Ask for 2026, get 100 matches ending 20 September, and the natural conclusion is that the season ended in September. Nothing in the response contradicts it: there is no total, no next-page marker, no truncation flag.

So this actor always sends an explicit limit, and warns whenever the number of matches returned equals the limit you asked for, naming the last date in the data and pointing out that it is where the data stops rather than where the season does. Raise limit (up to 1000) or ask for one month at a time.

Dates

• 20260920 — one day
• 202609 — a whole month (48 NFL matches across 13 dates)
• 2026 — a season, subject to the limit above
• 20260901-20260930 — rejected before the request is made. The API answers a dash range with HTTP 400, and it is the same 400 it returns for a league that does not exist, so sending it would produce an unhelpful error. Use the month form.

Every wrong input gets the same error

A bad sport, a bad league, a dash range and dates=notadate all return exactly {"code":400,"message":"Failed to get events endpoint."} — 55 bytes, byte identical. The API will not tell you which mistake you made, and there is no index endpoint to check against: /apis/site/v2/sports returns 404.

So this actor validates leagues, dates and limits locally first, and when a 400 still comes back its error names both possibilities rather than guessing one.

dates is a US-local day, not a UTC day

dates=20260920 returned 13 NFL matches dated 20 September and one dated the 21st at 00:20Z — an evening US kickoff that crosses UTC midnight. NHL did the same; Premier League, kicking off in the afternoon UK time, did not.

So the parameter picks ESPN's local match day while startsAt stays honest UTC. If you filter downstream on the UTC date, you will drop those late games.

Two different fields mean "rank"

Soccer standings carry a rank stat. NFL standings do not — they carry playoffSeed, labelled "Position". rank reads whichever exists, so it is filled for both. orderInGroup is kept separately: it is the position in the order the API returned, which is table order, and it does not always agree with playoffSeed (NFL returned seeds 1, 2, 3, 5, 4, 6 in that order).

A note on stat names in standings

A soccer table's stats are named pointsFor and pointsAgainst, with displayName: "Goals For" and "Goals Against". The machine name is identical in every sport and means something different in each, so stats and statLabels are both returned and the label travels with the number.