Build a scoreboard
A scoreboard line shows a game’s status, score, period and clock. This page shows how to read each one, then builds a box score from three REST reads.
The examples read the sample games, so they run without a key. In your app, the same objects come from statpad.games.getGame, the box score and roster endpoints, or the stream.
Game status
game.status has 11 values. Group them into four phases and render each phase its own way:
A complete game still changes. Statpad keeps polling a game for corrections for 3 hours after the final, and each correction arrives as a new version, like any other change. Statpad’s feed doesn’t send created or closed today, but handle them so your code keeps working when it does.
A postponed game works one of two ways, depending on the league. It either goes back to scheduled at its new time under the same id, or it stays postponed and its makeup is a new game. A makeup game’s rescheduled_from_id names the game it replaces, when Statpad knows it.
Start times
scheduled_at is the start time in UTC. A time_tbd game has no start time, so its scheduled_at is the start of the game’s day in US Eastern time. startLabel shows only the date for such a game:
For the NFL sample’s start time, and for a time_tbd game on the same day, startLabel returns:
A game whose date isn’t fixed yet, such as an NFL flex game, can still move to another day.
The period
live_state.period is a number. The league’s period_kind and regulation_periods, from GET /v1/leagues, turn it into a label:
Baseball’s period_kind is inning, and period_half says whether it’s the top or the bottom of the inning. Statpad serves no baseball league yet.
These are its labels for a regular-season game in each league. The soccer line also shows a cup game’s extra time and penalties:
The clock
The clock depends on the sport:
- Football, basketball and hockey.
clock_secondsis the time left in the period. A basketball clock rounds up, so0means the period is over. A hockey shootout has no clock, so itsclock_secondsisnull. - Soccer. The clock counts up, so
clock_secondsis alwaysnull. The match minute is inlive_state.soccer. Itsminuteandadded_minuteare the clock as shown, so 90’+6’ is minute 90 and added minute 6. Both arenullafter full time. - Baseball. There’s no clock, so
clock_secondsis alwaysnull. Show the inning, the outs and the count fromlive_state.baseballinstead.
Football, basketball and hockey feeds don’t say whether the clock is running, so clock_running is null there. In soccer, it’s true while a half or a period of extra time is under way.
Soccer plays carry the same minute and added_minute, so soccerMinute also labels events. These are the last two goals in the Premier League sample’s plays.json:
The score line
scoreLine puts the pieces together, with startLabel for games that haven’t started. It takes a response from GET /v1/{league}/games/{id} and the game’s league:
live_state is null until a game has live data, so a live game without one shows only the score. A hockey shootout has no clock, so its line ends at the period label. On the sample games, scoreLine returns:
The game read’s period_scores is an empty list today, so there’s no score by period yet. Coverage by league lists the fields that aren’t filled.
A schedule from GET /v1/{league}/games has each game’s status and score, but no live state. To show the period and clock for a list of games, read each game or follow it on the stream. Follow many games covers both.
Coverage
game.coverage says how much of a game the feed covers:
Every game Statpad serves today is full. Check coverage anyway, and hide the play-by-play and box score for a game that isn’t full. Coverage by league lists the fields each league fills.
Build a box score
A box score takes three reads of the same game:
GET /v1/{league}/games/{id}/boxscorehas one stat line per player.GET /v1/{league}/games/{id}/rosterhas who dressed for the game, with jerseys. Itsplayerslist has their names.GET /v1/{league}/games/{id}has the two teams.
A stat line carries only player_id and team_id, so join it to the roster’s players on the player’s id. Each line holds categories, such as passing and rushing. Each category holds stat codes, such as att and yards. A player has only the categories that apply to them, so treat every category and code as optional.
The box score’s teams list is empty today, so add up the player lines for team totals. Sum counts such as att and yards. Averages and longest plays don’t add up.
This script prints each team’s rushing lines and totals from the NFL sample:
A game roster read returns 100 entries per page by default. The sample game has 68 players, so one page holds them all. For a larger roster, page with paginate.
Keep it live
To update the box score during a game, seed the state map from Live updates with the three reads. Then apply the stream’s changes to it. The map’s key is entity_type and entity_id. For most types, entity_id is the entity’s own id. Three game-scoped types use another id:
Seed the map with the same keys, so each change from the stream replaces what REST returned:
Each of the three reads returns a seq. Subscribe from the lowest one, and the stream sends anything that changed after that read. A change you already hold leaves the same state when you apply it again.
On the NFL sample, the map seeded from the three files matches a map built from all 1,277 changes in changes.ndjson. Both hold the same 138 entries with the same payloads.
Game roster entries and stat lines use the player’s id as entity_id, so keep one map per game when you follow several games. Follow many games has a client that does this.