Leagues reference

Every league wired into Goalfeed's live polling loop today, its upstream data source, and an honest support tier.

Minimal working example

List the teams Goalfeed knows about for a league (useful for building watch.* config or a team picker):

bash

curl -s "http://localhost:8080/api/teams?leagueId=1" | python3 -m json.tool

Supported today

Tier	Meaning	Leagues
Live	Registered in the 1-second polling loop. A score change fires a real Home Assistant `goal` event and a WebSocket `event` message. A goal is always one point, so one score change is one event.	NHL, MLB

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 and NFL: not listed, pending verification

Both leagues have a client and service in this repo (IDs 5 and 6) — CFL polls cflscoreboard.cfl.ca plus a third-party sports-betting live-tracker feed (betstream.betgenius.com) for play detail; NFL polls ESPN's site.api.espn.com site API plus its "Fastcast" WebSocket for lower-latency push updates. Neither is listed above as supported. Live testing on 2026-08-20 found both leagues' score tracking broken — the CFL client discards a valid payload on a sportId/ competitionId type mismatch (BetGenius sends strings, the struct expects int), and the NFL client parses /summary?event= expecting a top-level events[] array that response doesn't have. With the score pinned or frozen, the score-diff detector never sees a change, so no goal event fires for either league today. Fixes are in progress; a league is listed again only once it's been verified working against a live game.

EPL is not a league here

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.

Set which teams to watch per league — configuration reference. Understand why score-diff detection has the consequences it does — Architecture.