Follow many games
The Quickstart follows one game. A scoreboard for a whole day needs every game that’s on. This page shows how many streams a plan can hold, how to start a stream from a snapshot, and how to follow a slate. It ends with two ways to poll instead.
One stream per game
league:<alias> carries the data a league’s games share. That’s teams, players, venues, seasons and weeks, plus rosters, injuries, transactions and depth charts. It carries no games, live states or plays. A live score comes only from the game’s own stream, so each game you show live needs a game:<id> subscription.
Your plan caps subscriptions per account, across all its connections and keys:
One connection holds at most 100 subscriptions. A stream past your plan’s cap, or past 100 on one connection, gets too_many_subscriptions for that stream. The connection stays open, and the other streams in the message still subscribe.
One subscribe message names 1 to 100 streams. A message with more gets bad_request for the whole message, with no stream set, and none of its streams subscribe.
If a day has more games than your plan’s cap, follow the games you show live and poll the schedule for the rest.
Start from a snapshot
A subscribe without resume starts from a snapshot. This is the way to start a league stream, which has no REST read to resume from. It also starts a game stream in one request, instead of the game, roster and box score reads.
The server sends:
subscribedwithmode: "snapshot"and aseq.- One or more
snapshotmessages, all with thatseq. Each holds up to 500 entities. The last one haslast: true. changes, starting atseq+ 1.
Buffer the entities until last arrives. Then replace your state for the stream with them, and record the seq. After that, apply changes as usual.
A league snapshot holds the league’s seasons, weeks, venues and teams, every player who has appeared in its games, rosters or injury reports, and its open injuries. A game snapshot holds the game, its live state, drives, plays, game roster and player stats. It also holds the teams, venue and players the game references.
A snapshot subscribe counts as one request against your allowance, whatever the snapshot’s size. It also takes one token from your snapshot bucket, which holds as many tokens as your plan has subscriptions. Resume subscribes, such as after a reconnect, don’t use the bucket. Rate limits has the details.
This module keeps one state map per stream. Game roster entries and stat lines use the player’s id as entity_id, so separate maps keep two games’ entries apart:
league.mts follows league:nfl. The first time it connects, it has no seq, so it subscribes for a snapshot. After a disconnect, it resumes from the last seq it applied:
A real league:nfl snapshot spans several messages. This run is against a test server that sends 1,200 players in three messages, then two changes, then closes the connection:
The second subscribe carried "resume": { "league:nfl": 42 }, so the server sent only seq 43. For production, add the backoff and error handling from Live updates.
Follow a slate
To follow a day of games:
- Read the day’s schedule.
- Subscribe to each game that’s live or starts within 30 minutes.
- Unsubscribe from each game when it ends.
- Read the schedule again every few minutes, to catch games as they start.
slate.mts does this for NCAAF on one connection. It uses streams.mts, so each game starts from a snapshot. Set maxSubscriptions to your plan’s cap:
en-CA formats the date as YYYY-MM-DD, the format date takes. A date with the default tz is a day in US Eastern time.
refresh subscribes to no more games than your free slots. If more games are on, poll the schedule for the rest. A failed schedule read logs the error, and the next refresh tries again.
The script doesn’t reconnect. When the connection closes, it stops reading the schedule and logs the close code. Stay connected shows how to reconnect and resume.
This run used a test server, with league set to "nfl" and a fixed date. A recorded NFL game replayed from the middle of the game to the final, and then the test server stopped:
The script frees each slot when the game is final, but corrections keep arriving for up to 3 hours after the final. If you store stats and have slots to spare, stay subscribed for that time. Otherwise, read the box score again later.
A game:<id> stream opens when the league publishes the game, which can be months before it starts. A subscription to an early game holds one of your slots until you unsubscribe.
Poll the schedule
If your screen shows only statuses and scores, you don’t need the stream. GET /v1/{league}/games returns each game’s status, away_score and home_score, with the teams. Each page counts as one request:
The loop stops once every game of the day is complete, closed, suspended, postponed or cancelled. At one page every 30 seconds, a 4-hour window costs 480 requests. This works on every plan, including Developer. The schedule has no period or clock, so read the game, or follow it, where you need them.
Poll the changes window
GET /v1/{league}/changes lists which entities changed in a time window, for clients that refetch rather than stream. Each entry names its entity_type, entity_id, game_id and latest version. Refetch what changed, then ask for the next window from window_end:
Against a test server that had just replayed a recorded game, the first pass printed:
The window rules:
- A window ends no later than 60 seconds ago, so a change shows up here at least a minute after it happens.
- A window spans at most 24 hours. With an older
from, page through one window at a time. window_endis where this window stopped. Pass it as the nextfrom, and you miss no change.- Each entity appears once per game it changed in, with its latest version.
- A page holds 1,000 entities by default and 5,000 at most. Every page of one window shares its
window_end.
For anything faster than a minute, use the stream, or poll one game’s GET /v1/{league}/games/{id}/changes as in Live updates.