Leagues reference
Every league Goalfeed has code for, its upstream data source, and an honest tier — not every league that has a client is one you can actually get a Home Assistant event from today.
Minimal working example
List the teams Goalfeed knows about for a league (useful for building
watch.* config or a team picker):
curl -s "http://localhost:8080/api/teams?leagueId=1" | python3 -m json.toolThree tiers, stated plainly
| Tier | Meaning | Leagues |
|---|---|---|
| Live | Registered in the 1-second/1-minute polling loop. A score change fires a
real Home Assistant goal event and a WebSocket
event message. |
NHL, MLB, CFL, NFL |
| API only | A full client and service exist and answer
/api/games/history, /api/upcoming, and
/api/teams, but the league is never registered in
main.go's live polling loop. No goal event will ever fire for
it. |
IIHF |
| Untracked WIP | Code exists, compiles, and is wired into both main.go and the
web API locally — but the source files are not committed to git, so
they are not part of any tagged release or the public repository as
published. Not something you can install today. |
Olympic Men's Hockey, Olympic Women's Hockey |
Per-league detail
| League | ID | Upstream source | What's detected | Tier |
|---|---|---|---|---|
| NHL | 1 |
api-web.nhle.com — an undocumented, unofficial NHL API |
Score change → one goal event per point (correct for hockey, where every goal is one point) | Live |
| MLB | 2 |
statsapi.mlb.com — the unofficial MLB Stats API |
Score change → one event per run | Live |
| CFL | 5 |
cflscoreboard.cfl.ca, plus a third-party sports-betting
live-tracker widget feed (betstream.betgenius.com) for play
detail — not a CFL-operated API |
Score change → one event per point — a converted touchdown (7 points) fires seven events, not one | Live |
| NFL | 6 |
ESPN's public site.api.espn.com site API, plus ESPN's
"Fastcast" WebSocket for lower-latency in-game push updates |
Same raw score-diff as CFL — a touchdown-plus-conversion fires seven events | Live |
| IIHF | 4 |
realtime.iihf.com |
Nothing — not polled by the background tickers at all | API only |
| Olympic Men's Hockey | 7 |
olympics.com's internal WMR API, hard-coded to the 2026 Winter
Games endpoint (wmr-owg2026) — will need a code change for
future Games, not a generic/configurable integration |
Score change → one event per goal. This is also the only
league service that populates Event.Type and
Event.Description — see the
WebSocket reference |
Untracked WIP |
| Olympic Women's Hockey | 8 |
Same as above | Same as above | Untracked WIP |
League ID 3 is reserved for EPL (English Premier League / soccer) in
models/league.go, and the bundled web UI still has a leftover EPL
icon/color mapping in its event-feed component. There is no
clients/leagues/epl or services/leagues/epl package at
all — it is an unused constant, not a supported or partially-supported
league. Nothing about EPL/soccer belongs in a Goalfeed config file.
All upstream sources are unofficial
Every API above is the same undocumented, unversioned endpoint each league's own website or app uses — not a published, contractually stable public API. Any of them can change shape or disappear without notice, and Goalfeed has no fallback if one does. See Architecture for why this is the project's biggest operational risk, not just a footnote.
Next
Set which teams to watch per league — configuration reference. Understand why score-diff detection has the consequences it does — Architecture.