Fundamentals
This page explains the concepts the rest of the guide builds on: how a college football year is organized, how the sport's divisions and conferences nest, which feeds carry game data, how coverage levels work, and what changes if you are coming from the NFL API. The mechanics (authentication, the URL shape, errors, and cache behavior) are on NCAAFB API Basics.
The Season Model
The Seasons catalog runs from 2013 and carries a single season type: every entry is REG. The season envelope is long, opening in late August and closing in early February, because the postseason is not a separate season type: the College Football Playoff and bowl games are addressed as tournaments under the REG season. The response below is trimmed to the first and the two most recent entries:
{
"league": {
"id": "26c1246a-2fc3-4b7e-8999-1685d3ab4676",
"name": "NCAA Football",
"alias": "NCAAFB"
},
"seasons": [
{
"id": "7010df8f-1e08-4021-91b8-ed09676c33de",
"year": 2013,
"start_date": "2013-08-29",
"end_date": "2014-01-14",
"status": "closed",
"type": {
"code": "REG"
}
},
{
"id": "754e4990-efc7-11ef-bb2a-5d2d22b9215e",
"year": 2025,
"start_date": "2025-08-23",
"end_date": "2026-01-26",
"status": "closed",
"type": {
"code": "REG"
}
},
{
"id": "fc822580-0db7-11f1-baa3-21a52b3e3c8d",
"year": 2026,
"start_date": "2026-08-29",
"end_date": "2027-02-01",
"status": "scheduled",
"type": {
"code": "REG"
}
}
]
}Season year plus REG address every seasonal feed, with {week_number} narrowing weekly feeds. For the playoff picture, start from the Tournament List and follow Tracking Playoffs.
Weeks, Byes, and the Postseason Path
The single REG season stretches to 21 weeks because the postseason rides inside it. The 2025 season shows the shape: 142 games in week 1 tapering to a single game in week 21, with game_type marking what each entry is:
regular(1,609 games) through the conference schedules, with 77 entries flaggedneutral_siteconference_championship(10) in week 15bowl(36) from week 16 onward, each carrying the bowl name intitleplayoff(34) from week 14: the FCS Playoffs and the College Football Playoff rounds
With 54 teams idle in week 2 alone, the bye_week array is long in every week; filter it to the teams you follow. The response below is trimmed to the first conference championship of the season:
{
"id": "754e4990-efc7-11ef-bb2a-5d2d22b9215e",
"year": 2025,
"type": "REG",
"name": "REG",
"weeks": [
{
"id": "077b3733-202c-4a56-86d1-093021bc240d",
"sequence": 15,
"title": "15",
"games": [
{
"id": "b62af0fd-7809-4ce6-87d3-e68a1c855383",
"status": "closed",
"scheduled": "2025-12-06T00:00:00+00:00",
"attendance": 18142,
"entry_mode": "LDE",
"coverage": "full",
"sr_id": "sr:match:66246604",
"game_type": "conference_championship",
"conference_game": false,
"title": "Conference USA Championship",
"duration": "3:18",
"parent_id": "d46489ed-6eb6-4cf1-966b-cf5748b4f301",
"expected_latency": 10,
"home": {
"id": "e2492d05-9414-41fb-b7ef-99b27cf358e6",
"name": "Jacksonville State Gamecocks",
"alias": "JVST",
"game_number": 13
},
"away": {
"id": "515e9431-e87d-4d3e-8916-3ecaa0a05034",
"name": "Kennesaw State Owls",
"alias": "KENN",
"game_number": 13
}
}
]
}
]
}The postseason games above also exist as tournaments. The Tournament List for a season names them with their dates, and the Tournament Schedule and Summary feeds add the bracket wiring and seeds that the flat season schedule does not carry:
{
"league": {
"id": "26c1246a-2fc3-4b7e-8999-1685d3ab4676",
"name": "NCAA Football",
"alias": "NCAAFB"
},
"season": {
"id": "754e4990-efc7-11ef-bb2a-5d2d22b9215e",
"year": 2025,
"type": "REG"
},
"tournaments": [
{
"id": "39a7ae3c-6097-42d2-913b-4a06f109e78e",
"name": "FCS Playoffs",
"location": "Nashville, TN, USA",
"status": "closed",
"start_date": "2025-11-29",
"end_date": "2026-01-05"
},
{
"id": "b760eaa9-3e31-499e-a655-2ed5bb05d9f7",
"name": "College Football Playoff",
"location": "Miami, FL, USA",
"status": "closed",
"start_date": "2025-12-19",
"end_date": "2026-01-19"
}
]
}Tracking Playoffs walks the bracket from these entries.
League Structure
College football is the API's largest structure: 6 divisions, 104 conferences, and 539 teams, from FBS through FCS, Division II and III, the NAIA, and the USCAA. The nesting order is the reverse of the NFL's: in the League Hierarchy, divisions sit at the top and conferences nest inside them. The response is shown with one division trimmed to one conference and its first two teams:
{
"league": {
"id": "26c1246a-2fc3-4b7e-8999-1685d3ab4676",
"name": "NCAA Football",
"alias": "NCAAFB"
},
"divisions": [
{
"id": "43d3cede-6b8f-4158-bc7f-c3c7365e5b32",
"name": "I-A",
"alias": "FBS",
"conferences": [
{
"id": "c7a491c8-d0f2-4ca1-9403-f82db4452dd1",
"name": "Southeastern",
"alias": "SEC",
"teams": [
{
"id": "d5199a36-7f26-4c3b-be48-9599039e232c",
"name": "Aggies",
"market": "Texas A&M",
"alias": "TXAM",
"founded": 1876,
"mascot": "Reveille",
"fight_song": "Aggie War Hymn",
"championships_won": 3,
"conference_titles": 18,
"playoff_appearances": 1,
"venue": {
"id": "889f7722-95bd-413a-9b1b-bbec46e490c7",
"name": "Kyle Field",
"city": "College Station",
"state": "TX",
"country": "USA",
"zip": "77843",
"address": "756 Houston Street",
"capacity": 102733,
"surface": "turf",
"roof_type": "outdoor",
"location": {
"lat": "30.6101",
"lng": "-96.3401"
}
},
"franchise": {
"id": "d5199a36-7f26-4c3b-be48-9599039e232c",
"name": "Aggies"
},
"team_colors": [
{
"type": "primary",
"hex_color": "#500000",
"rgb_color": {
"red": 80,
"green": 0,
"blue": 0
}
},
{
"type": "secondary",
"hex_color": "#ffffff",
"rgb_color": {
"red": 255,
"green": 255,
"blue": 255
}
}
]
},
{
"id": "2eef738d-c637-4b12-b8df-4b79efcce71e",
"name": "Bulldogs",
"market": "Georgia",
"alias": "UGA",
"founded": 1785,
"mascot": "Uga, Hairy Dawg",
"fight_song": "Hail to Georgia",
"championships_won": 4,
"conference_titles": 16,
"playoff_appearances": 5,
"venue": {
"id": "54cbb94e-27cc-4d25-ae2a-ae43645181ac",
"name": "Sanford Stadium",
"city": "Athens",
"state": "GA",
"country": "USA",
"zip": "30602",
"address": "100 Sanford Drive",
"capacity": 92746,
"surface": "turf",
"roof_type": "outdoor",
"location": {
"lat": "33.9498",
"lng": "-83.3734"
}
},
"franchise": {
"id": "2eef738d-c637-4b12-b8df-4b79efcce71e",
"name": "Bulldogs"
},
"team_colors": [
{
"type": "primary",
"hex_color": "#ba0c2f",
"rgb_color": {
"red": 186,
"green": 12,
"blue": 47
}
},
{
"type": "secondary",
"hex_color": "#000000",
"rgb_color": {
"red": 0,
"green": 0,
"blue": 0
}
}
]
}
]
}
]
}
]
}Three readings of the same structure:
- Division first, then conference.
FBSandFCSare divisions here (the catalog labels them I-A and I-AA), and each conference id scopes feeds like League Leaders - Ids at every level. Division, conference, and team ids from this feed address standings and rankings groupings across the API
- Teams carry their placement. Team objects in other feeds embed division and conference, so most integrations read the hierarchy once and cache it
The Division Catalog
The six divisions in the hierarchy, with the conferences and teams each one holds:
| Division | Alias | Conferences | Teams |
|---|---|---|---|
| I-A | FBS | 11 | 138 |
| I-AA | FCS | 18 | 128 |
| Division II | D2 | 19 | 164 |
| Division III | D3 | 31 | 43 |
| NAIA | NAIA | 24 | 58 |
| USCAA | USCAA | 1 | 8 |
The FBS and FCS aliases are the ones most integrations key on: FBS teams fill the College Football Playoff and the bowl calendar, FCS teams the FCS Playoffs, and the Rankings polls rank FBS teams.
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; NCAAFB teams carry no sr_id |
alias, market, name | UGA, Georgia, Bulldogs: schedule entries combine market and name into one name (Georgia Bulldogs) |
franchise | Mirrors the team's own id and name, since college programs stay put |
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": "754e4990-efc7-11ef-bb2a-5d2d22b9215e",
"year": 2025,
"type": "REG",
"name": "REG",
"week": {
"id": "73eacecf-7726-4de3-9419-3b821e998a83",
"sequence": 2,
"title": "2",
"games": [
{
"id": "fefcd061-2c97-4356-bf87-d11b398148fc",
"status": "closed",
"scheduled": "2025-09-05T23:00:00+00:00",
"attendance": 48717,
"entry_mode": "LDE",
"coverage": "full",
"sr_id": "sr:match:59838584",
"game_type": "regular",
"conference_game": false,
"duration": "3:33",
"expected_latency": 25,
"venue": {
"id": "e0947a41-9e85-488e-bcb3-6682dd56283e",
"name": "L&N Federal Credit Union Stadium",
"city": "Louisville",
"state": "KY",
"country": "USA",
"zip": "40209",
"address": "2800 S Floyd Street",
"capacity": 61000,
"surface": "artificial",
"roof_type": "outdoor"
},
"home": {
"id": "1e8edb90-ea5e-4663-9a65-a30e51583711",
"name": "Louisville Cardinals",
"alias": "LOU",
"game_number": 2
},
"away": {
"id": "b59ad9ae-b8ec-4f8e-9bd2-ec5b4af41e57",
"name": "James Madison Dukes",
"alias": "JMU",
"game_number": 2
},
"broadcast": {
"network": "ESPN2",
"satellite": "209"
},
"time_zones": {
"venue": "US/Eastern",
"home": "US/Eastern",
"away": "US/Eastern"
},
"weather": {
"condition": "Overcast ",
"humidity": 54,
"temp": 80,
"wind": {
"speed": 9,
"direction": "NW"
}
},
"scoring": {
"home_points": 28,
"away_points": 14
}
}
]
}
}| 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-05T23:00:00+00:00); convert with time_zones, which names the venue, home, and away zones |
coverage | full (live play-by-play for the whole game) or extended_boxscore (live Boxscore scores and clock, statistics after the game) |
expected_latency | How many seconds the game feeds may lag live play (25 here) |
game_type, title | regular, conference_championship, bowl, or playoff; title names championships, bowls, and playoff rounds |
parent_id | Present on recurring events such as bowl games and conference championships: every season's edition of the event shares one parent_id, so it can be followed across years |
conference_game, neutral_site | Whether both teams share a conference, and whether the venue belongs to neither |
entry_mode | The data-entry mode for the game; every game in the season shown reads LDE |
venue | Where the game is played, with surface and roof_type for weather-sensitive logic |
broadcast | The 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, the one URN NCAAFB entries carry |
Coverage
Coverage varies per game, and each schedule entry declares its own level in the coverage field: the 2025 season carries both full (live play-by-play depth) and extended_boxscore games. Read the flag from the schedule feeds and branch on it before wiring live play-by-play polling; Pulling Schedules covers where the field rides.
The 2025 season shows the split: 959 of 1,689 games (57%) carry full coverage and 730 carry extended_boxscore. What each level delivers:
| Level | Live during the game | After the game |
|---|---|---|
full | Boxscore, Play-by-Play, and Game Statistics update as plays are entered | Statistics pass through verification between complete and closed |
extended_boxscore | The Boxscore updates with scores and time remaining | Game Statistics and Play-by-Play detail fill in after the game |
Coverage is declared per game, not per team or conference, so read it from each schedule entry rather than caching a level per team.
Which level a game receives follows the teams involved: full coverage applies to any game with an FBS team, and to conference championships, bowls, and playoff games at both levels; regular-season games between two FCS teams, or against opponents from lower divisions, carry extended_boxscore. The level can change up to the scheduled start time, so read coverage again when a game moves to created rather than relying on the value stored from the season schedule.
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 College Football Playoff final's statistics, trimmed to the home team's summary and passing totals:
{
"id": "ac60aab5-2638-45de-87f0-037e3f199282",
"status": "closed",
"statistics": {
"home": {
"id": "fa0eb091-8e35-49c7-b00f-269794a99a61",
"name": "Hoosiers",
"market": "Indiana",
"alias": "IND",
"summary": {
"possession_time": "35:28",
"avg_gain": 4.4,
"safeties": 0,
"turnovers": 0,
"play_count": 72,
"rush_plays": 45,
"total_yards": 317,
"fumbles": 0,
"lost_fumbles": 0,
"penalties": 5,
"penalty_yards": 38,
"return_yards": 16
},
"passing": {
"totals": {
"attempts": 27,
"completions": 16,
"cmp_pct": 59.259,
"interceptions": 0,
"sack_yards": 23,
"rating": 117.13,
"touchdowns": 0,
"avg_yards": 6.2,
"sacks": 3,
"longest": 25,
"longest_touchdown": 20,
"redzone_attempts": 3,
"net_yards": 186,
"yards": 186,
"first_downs": 11,
"int_touchdowns": 0
}
}
}
}
}| 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, without the game-level summary and misc_returns, so a season view aggregates the way a game view does. The Game Statistics reference documents every field.
Coming from the NFL API
The two APIs share their feed grammar, so an NFL integration maps over with a handful of differences:
| Difference | What it means |
|---|---|
| One season type | The catalog is REG-only; the CFP and bowls are tournaments inside the season, so playoff logic starts from the Tournament List rather than a PST schedule |
| Hierarchy nests the other way | Divisions (FBS, FCS, and four more) contain conferences; in the NFL, conferences contain divisions |
| Per-game coverage levels | Games declare full or extended_boxscore in the coverage field; branch before assuming play-by-play depth |
| GUID-only ids | Rosters carry no sr_id URNs on teams or players; ids stay within the NCAAFB API, and NFL player profiles link back through their references |
| Class years on rosters | Player rows carry an eligibility value (FR, SO, JR, SR, 5TH, GR) with no NFL equivalent |
| Weeks run to 21 | Season schedules carry conference championships, bowls, and playoff games as game_type values inside the REG weeks; the NFL's 18 regular-season weeks hold regular games only |
| Rankings feeds | Poll-based rankings ride dedicated Rankings feeds alongside standings |
Updated about 20 hours ago