Football
The NFL (nfl) and NCAA Division I FBS football (ncaaf) share one data model. A game in either league fills the same endpoints and the same football blocks, so the same code reads both. The few fields that differ are under NFL and NCAAF.
The examples come from two recorded games: the Bills at the Vikings in the NFL, from Sample responses, and Arkansas at Auburn in NCAAF.
Live state
live_state on GET /v1/{league}/games/{id} carries the situation in its football block. The other sports’ blocks are null.
After the final, the last down, distance and yard line stay. The timeouts are null, because the feed stops reporting them. Sample responses shows a whole football live state from the 4th quarter.
Periods and overtime
Both leagues have a period_kind of quarter and 4 regulation_periods. Every period after the 4th is an overtime. Build a scoreboard turns a period number into a label such as 4th quarter or OT, and the clock section formats clock_seconds.
Plays
GET /v1/{league}/games/{id}/plays lists every play. It returns a page of plays, 500 by default and up to 1,000 with limit, with a next_cursor for the rest. Lists, pagination and dates shows how to page. A play’s type and its football.play_type are the same value, one of these:
The football block on each play:
Each play’s participants lists the players in it with a role: passer, rusher, receiver, tackler, assist_tackler (each player sharing a tackle), sacker, pass_defender, kicker, punter, returner, holder, snapper, scorer, pat_scorer (who scored the try), pat_passer, pat_rusher, fumbler, fumble_forcer, recoverer, penalized, or player for any other part. A player can have several roles on one play.
A player who isn’t on the game’s roster, such as a long snapper the feed doesn’t list, isn’t in participants. Join each participant’s player_id to players[].id in the game roster response, not to the box score, because a player in a play can have no stat line. During a live game, a play can arrive with an empty or partial list and fill in on a later version. The recorded NFL sample’s plays all have an empty list, because Statpad recorded that game before football plays listed their players.
description is the feed’s play text. Read the structured fields rather than parsing it.
Drives
GET /v1/{league}/games/{id}/play-groups lists the game’s drives, each with kind set to drive. A play’s group_id is the id of its drive. In both samples, every play has one, timeouts and the ends of quarters included.
This is the Bills’ first touchdown drive in the NFL sample, from play-groups.json, unedited:
The Bills went 80 yards in 8 plays and 3:18, from their own 20 into the end zone, between 4:02 and 0:44 of the 2nd quarter. team_id is the team with the ball, and the yard lines count from that team’s own goal line, so 100 is the end zone it attacks. start_clock and end_clock are seconds left in the period, and duration_seconds is the time of possession.
result is the feed’s own wording for how the drive ended. The two samples have Touchdown, Field Goal, Missed FG, Punt, Downs, Interception, Fumble, End of Half and End of Game. Treat it as display text, because the feed can send other values.
Box score
GET /v1/{league}/games/{id}/boxscore has one line per player. Each line’s stats holds categories, and each category holds stat codes:
field_goal_pct is a percentage, so 3 of 3 is 100. A code the feed leaves out for a game, such as qbr in the NFL sample, is missing from the line. A player only has the categories that apply to them, so treat every category and code as optional. Build a scoreboard joins the lines to player names and adds up team totals.
Rosters and injuries
GET /v1/{league}/games/{id}/roster lists every player the feed’s box score names, with their team and jersey. That can include a player with no stat line. The football feed has no game positions or starters, so position is null and starter is false.
GET /v1/nfl/injuries has the NFL injury report. Coverage by league describes the injury fields. NCAAF has no injuries.
What isn’t filled yet
These football fields are part of the API, but nothing fills them today:
Coverage by league lists the gaps every sport shares, such as team totals and the score by period.
NFL and NCAAF
The two leagues differ in a few fields: