API Basics

Sportradar's NFL 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 NFL 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 NFL statistics.

This page covers the practical basics of the NFL 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, league structure, and coverage concepts are on NFL Fundamentals.

Authentication

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

GET https://api.sportradar.com/nfl/official/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/nfl/official/{access_level}/v7/{language_code}/{feed}.{format}

access_level: trial or production, matching your key.
language_code: en (English). Each endpoint reference page lists the other language codes that feed accepts.
format: json or xml. Both carry the same data on every feed.

The NFL API organizes its data into logical endpoints, or feeds: 30+ 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 NFL 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, 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 version of the NFL 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 do support up to 3 versions (the current and 2 past versions) of our data APIs, per our Versioning Policy.

To access NFL v7, use v7 in each request to the API in the version parameter (the v7 segment of the URL shape above). To access previous versions, alter to v6 or v5. No other adjustment is necessary for access.

Related Football APIs

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

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

NFL 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 Profilerequest 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 NFL 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:

Seasons and Season Types

{season_year} is the calendar year in which the season begins. {season_type} selects the phase: PRE (preseason), REG (regular season), or PST (postseason). Season year plus season type address every seasonal feed, and {week_number} narrows the weekly feeds within them. The Seasons feed is the catalog of every season on file; NFL Fundamentals walks through the season model, including how far back each season type reaches and how the postseason bracket is also addressed as a tournament.

Complete Responses

Feeds return the complete data set for their scope in a single response, and no NFL endpoint uses pagination. A full Season Schedule, for example, returns every game of the season (272 games in the 18-week regular 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 4 hours 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 NFL data is collected by Sportradar's expert in-house operators and delivered two ways.

RESTful and Push

Most of our NFL 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 NFL API.

See our Push Feeds section for more info.

Change Log

The NFL 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

Interactive reference: every endpoint in the NFL Endpoints section can be exercised against your key from its reference page
Postman: our entire Media APIs are available on Postman; follow or fork the NFL API v7 collection to receive updates
XSD schemas: the NFL v7 schema zip file holds the entire NFL API v7 XSD schema, which describes the XML format
Simulations: replay past games on demand to exercise live-game handling at any time of year, including the Push feeds
MCP server: the Sportradar MCP server exposes the NFL feeds to AI-assisted development tools
Questions: check our NFL API FAQ or reach out to our support team at [email protected]