Skip to navigation

Football

The NFL and NCAAF, field by field. The live state, plays, drives, box score and what isn't filled yet.

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.

FieldWhat it is
periodThe quarter, 1 to 4. A later period is an overtime.
clock_secondsSeconds left in the quarter. The football feed moves the clock only when a play posts, so it doesn’t tick between plays.
clock_runningAlways null. The football feed doesn’t say whether the clock is running.
possession_team_idThe team with the ball, or null when the feed doesn’t say, as after the final.
football.downThe down, 1 to 4.
football.yards_to_goYards to a first down.
football.yardlineThe line of scrimmage, 0 to 100 from the possessing team’s own goal line. 95 is the opponent’s 5.
football.home_timeouts, football.away_timeoutsTimeouts each team has left in the half.

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:

play_typeThe play
passA pass, including sacks and interceptions
rushA run
punt, kickoff, field_goalA kick
extra_point, two_pointA try after a touchdown, filed as its own play. The feed often adds the try to the touchdown play instead, with the kicker as pat_scorer.
penaltyA play the feed files as a penalty, such as a false start
kneel, spikeA kneel-down or a spike
timeoutA timeout, official timeouts included
otherAnything else, such as the end of a quarter or the two-minute warning

The football block on each play:

FieldWhat it is
down, yards_to_goThe down and distance before the snap.
start_yardline, end_yardlineWhere the play started and ended, 0 to 100 from the offense’s own goal line. Read end_yardline for where this play ended rather than adding up yards. It isn’t always where the next play starts: after a touchdown at 100, the kickoff starts at 35. The next play’s start_yardline says where it starts. On a kick, the offense is the kicking team. On a turnover, end_yardline is the new offense’s spot, still counted from the snapping team’s goal line.
yards_gainedWhat the play itself gained. It’s 0 when a penalty wiped the play out.
penalty_yardsNet yards that penalties moved the ball, for (+) or against (-) the offense. On a run, a pass or another scrimmage play whose start, end and gain are all known, start_yardline + yards_gained + penalty_yards = end_yardline. Otherwise, as on a kick or a turnover, it’s the foul’s stated yardage, so the sum doesn’t hold. null without a penalty.
is_first_down, is_touchdown, is_turnoverWhat the play produced.
is_penaltyA foul on the play was enforced or offset. A play whose only foul was declined has false.
air_yardsHow far past the line of scrimmage the receiver caught the ball, negative behind it. Set on completed NFL passes only, and null on every other play.
play_action, screen_pass, run_pass_optionDeprecated and always null. No provider reports them.

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:

{
"football": {
"duration_seconds": 198,
"end_clock": 44,
"end_yardline": 100,
"first_downs": 4,
"play_count": 8,
"points": 7,
"start_clock": 242,
"start_yardline": 20,
"yards": 80
},
"game_id": "01a1d60f-67be-7bdd-83f4-53286521d9bb",
"id": "01a1d60f-762a-7889-b486-a3f704982cf9",
"kind": "drive",
"period": 2,
"period_half": null,
"result": "Touchdown",
"sequence": 13,
"team_id": "01a1d60f-67be-7bdf-ac2f-bcdeeac1da68",
"updated_at": "2026-11-13T17:58:20.485009Z",
"version": 12
}

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:

CategoryStat codes
passingatt, completions, yards, yards_per_attempt, touchdowns, interceptions, qbr; NFL also rating, sacks, sack_yards_lost
rushingatt, yards, yards_per_attempt, touchdowns, longest
receivingreceptions, yards, yards_per_reception, touchdowns, longest; NFL also targets
defensivetackles, solo_tackles, sacks, tackles_for_loss, passes_defended, touchdowns; NFL qb_hits, NCAAF qb_hurries
interceptionsinterceptions, yards, touchdowns
fumblesfumbles, lost, recovered
kickingfield_goals_made, field_goal_attempts, field_goal_pct, longest_field_goal, extra_points_made, extra_point_attempts, points
puntingpunts, yards, gross_average, inside_20, touchbacks, longest
kick_returns, punt_returnsreturns, yards, yards_per_return, longest, touchdowns

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:

FieldWhat you get today
play_action, screen_pass and run_pass_option on playsAlways null, because no provider reports them. They stay in the response so existing parsers keep working.
clock_running on the live statenull. Use status and clock_seconds.
position and starter on a game roster entrynull and false
primary_position on playersnull, except for NFL players who have been on the injury report
NCAAF injuriesAn empty list

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:

NFLNCAAF
air_yardsSet on completed passesAlways null, because the college feed has no yards after the catch
Passing codesAdds rating, sacks and sack_yards_lostNo rating, sacks or sack_yards_lost
Receiving codesAdds targetsNo targets
Defensive codesqb_hitsqb_hurries
InjuriesFilledNot filled
Play descriptionThe play textThe play text, which usually starts with the game clock, such as (13:49)