Fundamentals
This page explains the concepts the rest of the guide builds on: how an NFL year is organized, how the league is structured, which feeds carry game data, how coverage works, and what changes if you are coming from the NCAAFB API. The mechanics (authentication, the URL shape, errors, and cache behavior) are on NFL API Basics.
The Season Model
An NFL year is three seasons: preseason (PRE), an 18-week regular season (REG) of 272 games, and the postseason (PST) running from the Wild Card round through the Super Bowl. The Seasons feed is the catalog: REG and PST entries reach back to 2000, and PRE entries begin with 2015. The response below is trimmed to the three 2026 entries:
{
"league": {
"id": "3c6d318a-6164-4290-9bbc-bf9bb21cc4b8",
"name": "National Football League",
"alias": "NFL"
},
"seasons": [
{
"id": "c0650ee0-17f9-11f1-92c4-398db1c54270",
"year": 2026,
"start_date": "2026-08-06",
"end_date": "2026-08-30",
"status": "closed",
"type": {
"code": "PRE"
}
},
{
"id": "c0655d00-17f9-11f1-92c4-398db1c54270",
"year": 2026,
"start_date": "2026-09-09",
"end_date": "2027-01-10",
"status": "scheduled",
"type": {
"code": "REG"
}
},
{
"id": "c0655d01-17f9-11f1-92c4-398db1c54270",
"year": 2026,
"start_date": "2027-01-16",
"end_date": "2027-02-14",
"status": "scheduled",
"type": {
"code": "PST"
}
}
]
}Season year plus season type address every seasonal feed, and {week_number} narrows weekly feeds within them. The postseason bracket is also addressed as a tournament through the Tournament List family; Tracking Playoffs works through that path.
Weeks and Bye Weeks
Every schedule feed groups games into weeks, each with a sequence and a title, and the season types number their weeks differently:
PREruns weeks0to3. Week 0 holds a single game, the Hall of Fame Game, and each of the three weeks after it holds 16 gamesREGruns weeks1to18; the 2026 season holds 272 games, 24 of them carrying theflex-schedulestatus until the league fixes their kickoff (the Game Status Workflow page covers that status)PSTruns weeks1to4with 6, 4, 2, and 1 games: the Wild Card, Divisional, and Championship rounds, then the Super Bowl. Postseason entries carrygame_type: "playoff"and atitlesuch asNFC Wild CardorSuper Bowl LX
From week 5 onward a bye_week array lists the teams idle that week; 9 of the 18 regular-season weeks carry one in 2026. The response below is trimmed to week 5, its first game, and its two bye teams:
{
"id": "c0655d00-17f9-11f1-92c4-398db1c54270",
"year": 2026,
"type": "REG",
"name": "REG",
"weeks": [
{
"id": "1325b3fc-89d0-4bec-9f9c-7b754ce5f222",
"sequence": 5,
"title": "5",
"games": [
{
"id": "2b3761cb-3c86-43de-89d9-85175f844221",
"status": "scheduled",
"scheduled": "2026-10-09T00:15:00+00:00",
"entry_mode": "LDE",
"sr_id": "sr:match:71515872",
"game_type": "regular",
"conference_game": true,
"title": "Thursday Night Football",
"home": {
"id": "e627eec7-bbae-4fa4-8e73-8e1d6bc5c060",
"name": "Dallas Cowboys",
"alias": "DAL",
"game_number": 5,
"sr_id": "sr:competitor:4392"
},
"away": {
"id": "4254d319-1bc7-4f81-b4ab-b5e6f3402b69",
"name": "Tampa Bay Buccaneers",
"alias": "TB",
"game_number": 5,
"sr_id": "sr:competitor:4388"
}
}
],
"bye_week": [
{
"team": {
"id": "6680d28d-d4d2-49f6-aace-5292d3ec02c2",
"name": "Chiefs",
"alias": "KC",
"sr_id": "sr:competitor:4422"
}
},
{
"team": {
"id": "f14bf5cc-9a82-4a38-bc15-d39f75ed5314",
"name": "Panthers",
"alias": "CAR",
"sr_id": "sr:competitor:4415"
}
}
]
}
]
}Weekly feeds address the same structure by number (games/2026/REG/5/schedule.json), and the postseason exists twice: as the PST schedule above and as the NFL Playoffs tournament in the Tournament List, which adds bracket seeding and round wiring.
League Structure
The League Hierarchy feed carries the structure: two conferences, each holding four divisions, 32 teams in all. The response is shown with one conference trimmed to one division and its first two teams:
{
"league": {
"id": "3c6d318a-6164-4290-9bbc-bf9bb21cc4b8",
"name": "National Football League",
"alias": "NFL"
},
"conferences": [
{
"id": "1bdefe12-6cb2-4d6a-b208-b04602ae79c3",
"name": "AFC",
"alias": "AFC",
"divisions": [
{
"id": "b95cd27d-d631-4fe1-bc05-0ae47fc0b14b",
"name": "AFC East",
"alias": "AFC_EAST",
"teams": [
{
"id": "768c92aa-75ff-4a43-bcc0-f2798c2e1724",
"name": "Bills",
"market": "Buffalo",
"alias": "BUF",
"sr_id": "sr:competitor:4376",
"founded": 1960,
"owner": "Terry and Kim Pegula",
"general_manager": "Brandon Beane",
"president": "Terry Pegula",
"mascot": "Billy Buffalo",
"fight_song": "Shout",
"championships_won": 0,
"conference_titles": 4,
"division_titles": 15,
"playoff_appearances": 25,
"venue": {
"id": "29afbde0-48c0-11f1-8f3e-590feb5b9cd1",
"name": "Highmark Stadium",
"city": "Orchard Park",
"state": "NY",
"country": "USA",
"zip": "14127",
"address": "10 Bills Plaza",
"capacity": 63000,
"surface": "turf",
"roof_type": "outdoor",
"sr_id": "sr:venue:8171",
"location": {
"lat": "42.77305339290525",
"lng": "-78.7921408708847"
}
},
"franchise": {
"id": "26f22bc6-1fb9-4c01-80cc-908342490651",
"name": "Bills",
"alias": "BUF"
},
"team_colors": [
{
"type": "secondary",
"hex_color": "#c60c30",
"alpha": 0.0,
"rgb_color": {
"red": 198,
"green": 12,
"blue": 48
}
},
{
"type": "primary",
"hex_color": "#00338d",
"alpha": 0.0,
"rgb_color": {
"red": 0,
"green": 51,
"blue": 141
}
}
]
},
{
"id": "4809ecb0-abd3-451d-9c4a-92a90b83ca06",
"name": "Dolphins",
"market": "Miami",
"alias": "MIA",
"sr_id": "sr:competitor:4287",
"founded": 1966,
"owner": "Stephen M. Ross",
"general_manager": "Jon-Eric Sullivan",
"president": "Tom Garfinkel",
"mascot": "T. D.",
"nicknames": "Phins",
"fight_song": "Miami Dolphins No. 1",
"championships_won": 2,
"championship_seasons": "1972, 1973",
"conference_titles": 5,
"division_titles": 13,
"playoff_appearances": 25,
"venue": {
"id": "50a5c833-1570-4c38-abc7-7914cf87dbde",
"name": "Hard Rock Stadium",
"city": "Miami Gardens",
"state": "FL",
"country": "USA",
"zip": "33056",
"address": "2269 Northwest 199th Street",
"capacity": 65326,
"surface": "turf",
"roof_type": "outdoor",
"sr_id": "sr:venue:21306",
"location": {
"lat": "25.958025",
"lng": "-80.238724"
}
},
"franchise": {
"id": "d20c28e5-568a-4a6e-8b17-a8b2108e0eb9",
"name": "Dolphins",
"alias": "MIA"
},
"team_colors": [
{
"type": "secondary",
"hex_color": "#fc4c02",
"alpha": 0.0,
"rgb_color": {
"red": 252,
"green": 76,
"blue": 2
}
},
{
"type": "primary",
"hex_color": "#008e97",
"alpha": 0.0,
"rgb_color": {
"red": 0,
"green": 142,
"blue": 151
}
}
]
}
]
}
]
}
]
}Three readings of the same structure:
- Ids at every level. League, conference, division, and team ids from this feed address standings groupings and appear on team entries across the API
- Teams carry their placement. Team objects in other feeds embed their conference and division, so most integrations read the hierarchy once and cache it
sr_idURNs ride alongside. Teams carrysr:competitor:ids and players carrysr:player:ids for joining NFL data to other Sportradar products
Conferences and Divisions
The full catalog, with each division's teams by alias:
| Division | Alias | Teams |
|---|---|---|
| AFC East | AFC_EAST | BUF, MIA, NYJ, NE |
| AFC North | AFC_NORTH | CIN, CLE, BAL, PIT |
| AFC South | AFC_SOUTH | IND, JAC, HOU, TEN |
| AFC West | AFC_WEST | DEN, LAC, KC, LV |
| NFC East | NFC_EAST | WAS, DAL, PHI, NYG |
| NFC North | NFC_NORTH | CHI, DET, GB, MIN |
| NFC South | NFC_SOUTH | TB, ATL, CAR, NO |
| NFC West | NFC_WEST | SF, ARI, LA, SEA |
Team Identity
Team objects repeat a small identity block across the API; the hierarchy entry above shows the full form:
| Field | What it carries |
|---|---|
id | The team GUID that every team-scoped feed takes in its path |
sr_id | The sr:competitor: URN for joins to other Sportradar products; venues carry sr:venue: and games sr:match: |
alias, market, name | BUF, Buffalo, Bills: schedule entries combine market and name into one name (Buffalo Bills) |
franchise | The franchise the team belongs to, the key that survives a relocation (ID Handling covers relocations) |
venue | Home venue with capacity, surface, roof type, and coordinates |
team_colors | Primary and secondary colors as hex and RGB values, ready for display |
The Game Feed Set
Four feeds share one game id and divide the work of describing a game:
| Feed | Role |
|---|---|
| Game Boxscore | The live one-call view: score by quarter, situation, scoring plays, and team summaries |
| Game Play-by-Play | Every drive, play, and event with situations and per-play statistics |
| Game Statistics | Full team and player statistic lines for the game |
| Game Roster | Who is present for this specific game, with per-game player status |
Tracking Live Games shows when to poll each, and the Game Status Workflow page defines the statuses that drive the polling.
Anatomy of a Game Entry
Schedule entries are the game header every game feed repeats. A completed game from week 2 of the 2025 season, with its period scoring omitted:
{
"id": "fbe26310-feb8-11ef-a86e-d5de4289b45b",
"year": 2025,
"type": "REG",
"name": "REG",
"week": {
"id": "efb8dd84-bdba-4136-b518-7159a02ff8db",
"sequence": 2,
"title": "2",
"games": [
{
"id": "b0563750-d49e-4362-b862-8439170dd4b7",
"status": "closed",
"scheduled": "2025-09-12T00:15:00+00:00",
"attendance": 77289,
"entry_mode": "LDE",
"sr_id": "sr:match:60574797",
"game_type": "regular",
"conference_game": true,
"title": "Thursday Night Football",
"duration": "3:12",
"venue": {
"id": "5a60dd3a-302c-41c6-ab0f-dd335c1103c2",
"name": "Lambeau Field",
"city": "Green Bay",
"state": "WI",
"country": "USA",
"zip": "54304",
"address": "1265 Lombardi Avenue",
"capacity": 81441,
"surface": "turf",
"roof_type": "outdoor",
"sr_id": "sr:venue:8183"
},
"home": {
"id": "a20471b4-a8d9-40c7-95ad-90cc30e46932",
"name": "Green Bay Packers",
"alias": "GB",
"game_number": 2,
"sr_id": "sr:competitor:4420"
},
"away": {
"id": "22052ff7-c065-42ee-bc8f-c4691c50e624",
"name": "Washington Commanders",
"alias": "WAS",
"game_number": 2,
"sr_id": "sr:competitor:4432"
},
"broadcast": {
"network": "Amazon Prime Video"
},
"time_zones": {
"venue": "US/Central",
"home": "US/Central",
"away": "US/Eastern"
},
"weather": {
"condition": "Overcast",
"humidity": 78,
"temp": 65,
"wind": {
"speed": 7,
"direction": "ESE"
}
},
"scoring": {
"home_points": 27,
"away_points": 18
}
}
]
}
}| Field | What it carries |
|---|---|
status | The lifecycle state (scheduled, created, inprogress, halftime, complete, closed, and the exceptions); the Game Status Workflow page defines each |
scheduled | Kickoff in UTC (2025-09-12T00:15:00+00:00); convert with time_zones, which names the venue, home, and away zones |
game_type, title | regular or playoff; title names TV windows and rounds (Thursday Night Football, Super Bowl LX) |
parent_id | Present on recurring events: every Super Bowl carries the same parent_id, so one key follows the game across seasons |
conference_game | Whether both teams share a conference |
entry_mode | The data-entry mode for the game; every game in the seasons shown reads LDE |
venue | Where the game is played, with surface and roof_type for weather-sensitive logic |
broadcast | The national broadcaster (network), plus satellite, internet, and radio where available |
attendance, duration, weather | Filled once the game is played; weather reports conditions at kickoff |
scoring | Final points once the game is complete, with a periods array of quarter scores (omitted above) |
sr_id | The sr:match: URN of the game |
Coverage
Coverage is uniform: every game is served by the full game-feed quartet with live play-by-play, so integrations never branch on a per-game coverage level. Where depth varies is time, not games: statistics pass through post-game verification between complete and closed, and the Game Status Workflow page describes that window.
Statistic Categories
Game Statistics, Seasonal Statistics, and Player Profiles share one vocabulary of statistic categories. Each category holds team totals and, for most, a players array of individual lines. The Super Bowl LX statistics, trimmed to the home team's summary and passing totals:
{
"id": "7391a8d0-6675-4305-92fc-dc65bb4dcd38",
"status": "closed",
"title": "Super Bowl LX",
"statistics": {
"home": {
"id": "97354895-8c77-4fd4-a860-32e62ea7382a",
"name": "Patriots",
"market": "New England",
"alias": "NE",
"sr_id": "sr:competitor:4424",
"summary": {
"possession_time": "26:49",
"avg_gain": 4.9,
"safeties": 0,
"turnovers": 3,
"play_count": 67,
"rush_plays": 18,
"total_yards": 331,
"fumbles": 1,
"lost_fumbles": 1,
"penalties": 3,
"penalty_yards": 25,
"return_yards": 4
},
"passing": {
"totals": {
"attempts": 43,
"completions": 27,
"cmp_pct": 62.791,
"interceptions": 2,
"sack_yards": 43,
"rating": 79.1,
"touchdowns": 2,
"avg_yards": 5.143,
"sacks": 6,
"longest": 35,
"longest_touchdown": 35,
"air_yards": 166,
"redzone_attempts": 2,
"net_yards": 252,
"yards": 295,
"first_downs": 14,
"int_touchdowns": 1,
"throw_aways": 2,
"poor_throws": 10,
"defended_passes": 4,
"dropped_passes": 0,
"spikes": 0,
"blitzes": 10,
"hurries": 9,
"knockdowns": 3,
"pocket_time": 117.324,
"avg_pocket_time": 2.728,
"batted_passes": 2,
"on_target_throws": 27
}
}
}
}
}| Category | Level |
|---|---|
summary | team level only |
rushing | team totals and a players list |
receiving | team totals and a players list |
punts | team totals and a players list |
punt_returns | team totals and a players list |
penalties | team totals and a players list |
passing | team totals and a players list |
misc_returns | team totals and a players list |
kickoffs | team totals and a players list |
kick_returns | team totals and a players list |
int_returns | team totals and a players list |
fumbles | team totals and a players list |
field_goals | team totals and a players list |
defense | team totals and a players list |
extra_points | team level only |
first_downs | team level only |
interceptions | team level only |
touchdowns | team level only |
efficiency | team level only |
The Seasonal Statistics feed carries the same categories under record and opponents (everything except the game-level summary), so a season view aggregates the way a game view does. The Game Statistics reference documents every field.
Coming from the NCAAFB API
The two APIs share their feed grammar, so a college football integration maps over with a handful of differences:
| Difference | What it means |
|---|---|
| Three season types | PRE, REG, and PST are separate catalog entries and separate schedule paths; the postseason is both the PST schedule and a tournament |
| Conferences contain divisions | Two conferences of four divisions each; the hierarchy nests conference, then division, then team |
| Uniform coverage | Every game carries full live coverage, so schedule entries omit the coverage and expected_latency fields and integrations never branch on a level |
| URNs on teams, venues, and games | sr_id values (sr:competitor:, sr:venue:, sr:match:) ride alongside GUIDs for joins to other Sportradar products |
| Weekly team feeds | Depth charts, injuries, transactions, and free agents ride dedicated feeds, and roster rows carry a roster status rather than a class-year eligibility |
| The draft | Prospects, picks, and trades ride the draft feeds; Tracking the Draft covers them |
| Languages | Feeds accept 13 language codes; the NCAAFB API serves en only |
Updated about 10 hours ago