Integration GuidesReference Docs
Coverage MatrixDocumentationChange LogLog InContact Us
Integration Guides
Coverage MatrixDocumentationChange LogLog InContact Us

API Basics

Sportradar's NCAA Football (NCAAFB) data is delivered as a RESTful B2B (Business-to-Business) API. HTTP requests are made using the API authentication access established in your account, and data can be returned in either JSON or XML format.

The NCAA Football API is a Sportradar League-Based API. This means it was designed specifically for the sport of football, with the aim of providing our media customers with in-depth, intuitive, and speedy NCAAFB statistics.

This page covers the practical basics of the NCAAFB API: authentication, URL structure, seasons and season types, formats, errors, cache behavior, time values, and delivery options. The payloads themselves are covered in the scenario pages; the season model, divisions and conferences, and coverage levels are on NCAAFB Fundamentals.


Authentication

Every request is authenticated with your API key in the x-api-key header:

GET https://api.sportradar.com/ncaafb/trial/v7/en/league/hierarchy.json
x-api-key: YOUR_API_KEY

Keep the key server-side; do not embed it in client applications.

To accept data from our API feeds, ensure that your application also:

  • Supports TLS 1.2 or above
  • Can follow an HTTP redirect (used in Push and the Images API)

Base URL and URL Structure

All REST requests follow one URL shape:

GET https://api.sportradar.com/ncaafb/{access_level}/v7/{language_code}/{feed}.{format}
  • access_level: trial or production, matching your key.
  • language_code: en (English).
  • format: json or xml. Both carry the same data on every feed.

The NCAA Football API organizes its data into logical endpoints, or feeds: 20 distinct feeds, each with a focused purpose to allow for efficient data retrieval. To access a team schedule you retrieve a "schedule" feed such as Season Schedule; to access a game you retrieve a "game" feed such as Game Play-by-Play or Game Statistics. Depending on your specific need, different feeds and pull frequencies will be needed. Use our NCAAFB Endpoints section for feed documentation and an interactive sandbox.

Most feeds take a unique ID or parameter in the path: a season year and season type, a week number, a date, a poll type, or a game, team, player, or tournament ID. To retrieve these IDs you may have to iterate through feeds with larger data sets; see our ID Handling section for more info on Sportradar IDs, and the API map below for which identifier each feed takes.


Versioning

The current and only version of the NCAA Football API is v7. We strongly recommend using the latest version of all of our APIs, as these will be the most stable and robust offerings. However, we generally support up to 3 versions (the current and 2 past versions) of our data APIs, per our Versioning Policy.

To access NCAA Football v7, use v7 in each request to the API in the version parameter (the v7 segment of the URL shape above).


Related Football APIs

We provide three additional football data APIs: NFL, UFL, and Global American Football.

The NFL and UFL APIs have the exact same structure as college football, with the only differences being those necessitated by the league structures themselves. For example, Standings data in the NFL behaves differently than Rankings in NCAA Football. And overtime rules in the UFL require slightly different data points at a game level from the NCAA Football API.

The Global American Football API is a separate structure, adhering to our General Sport API format. Integration with the "Global" API is not covered in this guide.


NCAAFB API Map

Here is a retrieval path for a player profile.

Player Profile Retrieval Paththree requests from a cold start
1. Team idLeague Hierarchy⇄Teamseither feed lists every team; take the team id
2. Player idTeam Rosterrequest with the team id; the roster carries each player id
3. Player detailPlayer Profilebiographical info, draft info, and seasonal stats
ID Handling covers the ID families; each endpoint reference page lists the fields the feed carries.

All NCAAFB API feeds follow this pulling logic. Visit our Integration Scenarios section for specific retrieval scenarios.

The map below shows how the entire API is interconnected; every pill links its endpoint reference page:

NO ID NEEDEDDATESEASON / WEEKGAME IDTEAM IDPLAYER IDTOURNAMENT IDGetting OrientedSTART HERE · SCHEDULES PROVIDE GAME AND TEAM IDS Seasons League Hierarchy Teams Current Season Schedule Current Week Schedule Season Schedule Weekly ScheduleTrack Games LiveGAME IDS COME FROM THE SCHEDULE FEEDS Game Boxscore Game Statistics Game Play-by-Play Game RosterTeams and PlayersIDS COME FROM TEAMS AND ROSTERS Team Roster Player Profile Transfer PortalFollow the SeasonTAKE A SEASON YEAR AND TYPE · STATS ADD A TEAM ID Postgame Standings League Leaders Seasonal StatisticsAwards ListSeasonal AwardsRankings and PollsPOLL RANKINGS TAKE A POLL TYPE AND SEASON YEAR Rankings (Current Week) Rankings (By Week)TournamentsTOURNAMENT LIST PROVIDES TOURNAMENT IDS Tournament List Tournament Schedule Tournament SummaryMonitor Data Changes Daily Change Log Daily TransactionsLive PushREALTIME ADD-ON · SUBSCRIBE, NO ID REQUIRED Push Events Push Statistics

Seasons and Season Types

{season_year} is the calendar year in which the season begins. The Seasons catalog runs from 2013 and carries a single season type, so {season_type} is always REG: the College Football Playoff and bowl games are addressed as tournaments under the REG season rather than as a separate postseason type, and the season envelope runs from late August to early February. Season year plus REG address every seasonal feed, with {week_number} narrowing the weekly feeds. NCAAFB Fundamentals walks through the season model and the tournament path to the playoff picture.


Complete Responses

Feeds return the complete data set for their scope in a single response, and no NCAAFB endpoint uses pagination. A full Season Schedule, for example, returns every game of the season in one payload, and each response provides all data available for the request.


Errors

  • Authentication failures return 403 with an HTML page, not a JSON or XML error object; branch on the status code:
<!DOCTYPE html>
      <html lang="en">
        <head>
          <meta charset="utf-8">
          <title>Authentication Error</title>
        </head>
        <body>
          <p>Authentication Error</p>
        </body>
      </html>
  • Rate-limit errors return 429 Too Many Requests; slow your request rate and retry, increasing the wait between attempts
  • 404 indicates an unknown ID or path
  • Other statuses follow the Response Codes page

Cache Behavior

Each REST response carries a Cache-Control header stating how long the payload may be served from cache, for example Cache-Control: public, must-revalidate, max-age=300 (a TTL of 300 seconds). TTLs are tiered by feed family and by game activity: the game feeds move from 60 seconds while a game is scheduled to 3 seconds while it is inprogress, 600 seconds once it is closed, and 30 minutes seven days after that, while standings hold a 10-minute cache with the data updating as games conclude. TTL is an upper bound, not a guarantee: when the underlying data changes, the cached object is replaced immediately, even if the TTL has not expired. The per-feed chart is on the Update Frequencies page.

⚠️

A TTL Is Not a Polling Recommendation

A short TTL means the payload can change that often, not that you should request it that often. Check the header on each response you receive, and match your polling cadence to the freshness your product actually needs. Recommended cadences are on the Update Frequencies page and in each scenario's Best Practices.


Time Values

Timestamps are UTC ISO 8601: scheduled values carry an explicit +00:00 offset, and change-log last_modified values use the Z suffix. Date-only fields such as season dates carry no time zone. The date-scoped feeds (Daily Change Log, Daily Transactions) are keyed to the league-defined day rather than the UTC calendar day: both feeds state their window in start_time and end_time (04:00:00Z to 03:59:59Z the next morning), so a change entered on a US evening belongs to that US date's feed even when its UTC timestamp has rolled past midnight. Plan date math accordingly.


Delivery Options

All NCAA Football data is collected by Sportradar's expert in-house operators and delivered two ways.


RESTful and Push

Most of our NCAAFB endpoints are RESTful, but we also include complementary Push feeds available for Realtime customers.

With RESTful feeds, a request must be made whenever a data update is needed. For our Push feeds, one request will open up a streaming connection. Data is then delivered in a continuous stream indefinitely.

Push feeds correlate to the RESTful endpoints, but are not necessarily 1:1 in parity. For example, the Push Events feed follows the same format, and includes nearly all of the same data, as the Game Play-by-Play RESTful endpoint. And Push Statistics correlates to Game Statistics.

For increased data speed, and fewer API requests, many customers use Push. Though it is important to note that Push feeds are not meant to replace the RESTful data, but to enhance it. RESTful feeds should always be used as the backbone of the NCAAFB API.

See our Push Feeds section for more info.


Change Log

The NCAAFB API includes a Daily Change Log feed, which is used to catch updates for teams, players, game stats, schedules, and standings.

A request is made for a specific date, which then returns a list of unique IDs and timestamps of updates on that day. You can then use these IDs to retrieve stat updates from other endpoints. This allows for quick and efficient data retrieval, and is a common concept across all integration scenarios.

See our Monitoring Data Changes guide for detail on how to efficiently leverage this feed.


Integration Resources

Updated 8 days ago

Did this page help you?

© Sportradar AG, St. Gallen, Switzerland