Pulling Schedules

Schedule feeds are the backbone of an NFL integration: they carry every game's ID, participants, venue, broadcast, weather, status, and (once games finish) quarter-by-quarter scoring. Most other scenarios start here; to retrieve live game data, for instance, you first pull a schedule feed to obtain the game IDs for the games you are targeting. This scenario confirms the season, loads its schedule, keeps the near-term window fresh, and reconciles schedule changes. Responses are shown trimmed to representative slices.

This scenario is commonly used to:

Populate season and week schedule views
Discover game IDs for boxscore, play-by-play, and statistics drilldowns
Show final scores and quarter splits without polling game feeds
Detect postponements, reschedules, and deleted games
Lay out postseason matchups from the Tournament Schedule

Relevant Feeds

Feed	Scope	Use
Season Schedule	`{season_year}/{season_type}`	Complete schedule for a given season (past, current, or upcoming), including venue and broadcast info and scoring results by quarter
Weekly Schedule	season + `{nfl_season_week}`	One week of a season, including venue, weather conditions, broadcast info, and scoring results by quarter, plus the `deleted_games` list
Current Season Schedule	none	The current season without knowing the year
Current Week Schedule	none	The current week without tracking week numbers
Tournament Schedule	`{tournament_id}`	Date, time, location, and other event details for every matchup in a given tournament
Seasons	none	Season catalog: the prerequisite for every season-scoped feed

High-Level Workflow

Schedule WorkflowLoad the season once, then refresh the near-term window

BootstrapSeasons→Season Schedulestore game and team IDs

RefreshCurrent Week ScheduleWeekly Schedulescores fill in when a game reaches complete

PostseasonTournament Schedulematchups by round; teams fill in as berths are set

Reconciledeleted_gamesdrop listed IDs; a postponed game's makeup arrives as a new ID

MonitorDaily Change Logrefetch the week that carries a changed game

Dashed pill = optional depth. Cadences come from Update Frequencies.

Integration Steps

1. Confirm the season

Every season-scoped schedule feed takes a {season_year}/{season_type} pair, so start from the Seasons catalog to confirm which seasons and season types are on file:

GET https://api.sportradar.com/nfl/official/trial/v7/en/league/seasons.json
x-api-key: YOUR_API_KEY

To avoid confusion and ensure you're accessing available data, refer to our Seasons feed. This resource lists all the seasons for which we have data.

For example: To ensure data availability for future seasons, such as a schedule in advance of when a season begins, first check the Seasons feed to verify that data for that specific season is already provided.

Starting with this feed can prevent unnecessary errors and streamline your data retrieval process.

📅
Schedule Release Timing
Schedules in the NFL API (Preseason PRE, Regular Season REG, and Postseason PST) are typically released by the league in May. Once officially announced, the full season schedule is ingested and made available in the API shortly after.
Expected Availability: Schedule data is generally available within 2 to 3 hours of the league’s official release. Full schedule data is expected to be available within 3 hours.

2. Load the season

Pull the Season Schedule for the season and type you cover; it returns past, current, and upcoming seasons alike. The response nests weeks[], each with games[], and every game carries venue and broadcast info and scoring results by quarter. Store the game IDs, team IDs, and scheduled times:

GET https://api.sportradar.com/nfl/official/trial/v7/en/games/2025/REG/schedule.json
x-api-key: YOUR_API_KEY

{
    "id": "fbe26310-feb8-11ef-a86e-d5de4289b45b",
    "year": 2025,
    "type": "REG",
    "name": "REG",
    "weeks": [
        {
            "id": "f9ddc73d-e2e0-490b-85af-1126a9fbb1c5",
            "sequence": 1,
            "title": "1",
            "games": [
                {
                    "id": "56779053-89da-4939-bc22-9669ae1fe05a",
                    "status": "closed",
                    "scheduled": "2025-09-05T00:20:00+00:00",
                    "attendance": 69879,
                    "entry_mode": "LDE",
                    "sr_id": "sr:match:60525453",
                    "game_type": "regular",
                    "conference_game": true,
                    "duration": "3:55",
                    "venue": {
                        "id": "4fa8c29c-6626-464c-8540-314ed7535e1b",
                        "name": "Lincoln Financial Field",
                        "city": "Philadelphia",
                        "state": "PA",
                        "country": "USA",
                        "zip": "19148",
                        "address": "1020 Pattison Avenue",
                        "capacity": 69596,
                        "surface": "turf",
                        "roof_type": "outdoor",
                        "sr_id": "sr:venue:1833"
                    },
                    "home": {
                        "id": "386bdbf9-9eea-4869-bb9a-274b0bc66e80",
                        "name": "Philadelphia Eagles",
                        "alias": "PHI",
                        "game_number": 1,
                        "sr_id": "sr:competitor:4428"
                    },
                    "away": {
                        "id": "e627eec7-bbae-4fa4-8e73-8e1d6bc5c060",
                        "name": "Dallas Cowboys",
                        "alias": "DAL",
                        "game_number": 1,
                        "sr_id": "sr:competitor:4392"
                    },
                    "broadcast": {
                        "network": "NBC/Peacock"
                    },
                    "time_zones": {
                        "venue": "US/Eastern",
                        "home": "US/Eastern",
                        "away": "US/Central"
                    },
                    "weather": {
                        "condition": "Rain",
                        "humidity": 66,
                        "temp": 75,
                        "wind": {
                            "speed": 11,
                            "direction": "S"
                        }
                    },
                    "scoring": {
                        "home_points": 24,
                        "away_points": 20
                    }
                }
            ]
        }
    ]
}

<?xml version="1.0" ?>
<?xml-stylesheet type="text/xsl" charset="UTF-8" href="/xslt/football/schedule-v7.0.xsl"?>
<!-- Generation started @ 2026-09-01 09:00:21 +0000 -->
<season xmlns="http://feed.elasticstats.com/schema/football/schedule-v7.0.xsd" id="fbe26310-feb8-11ef-a86e-d5de4289b45b" year="2025" type="REG" name="REG">
  <week id="f9ddc73d-e2e0-490b-85af-1126a9fbb1c5" sequence="1" title="1">
    <game id="56779053-89da-4939-bc22-9669ae1fe05a" status="closed" scheduled="2025-09-05T00:20:00+00:00" attendance="69879" entry_mode="LDE" sr_id="sr:match:60525453" game_type="regular" conference_game="true" duration="3:55">
      <venue id="4fa8c29c-6626-464c-8540-314ed7535e1b" name="Lincoln Financial Field" city="Philadelphia" state="PA" country="USA" zip="19148" address="1020 Pattison Avenue" capacity="69596" surface="turf" roof_type="outdoor" sr_id="sr:venue:1833">
        <location lat="39.900872" lng="-75.167311"/>
      </venue>
      <home id="386bdbf9-9eea-4869-bb9a-274b0bc66e80" name="Philadelphia Eagles" alias="PHI" game_number="1" sr_id="sr:competitor:4428"/>
      <away id="e627eec7-bbae-4fa4-8e73-8e1d6bc5c060" name="Dallas Cowboys" alias="DAL" game_number="1" sr_id="sr:competitor:4392"/>
      <broadcast network="NBC/Peacock"/>
      <time_zones venue="US/Eastern" home="US/Eastern" away="US/Central"/>
      <weather condition="Rain" humidity="66" temp="75">
        <wind speed="11" direction="S"/>
      </weather>
      <scoring home_points="24" away_points="20">
        <quarter id="13fb09bc-7a02-433b-9c30-17bfe5db9f65" number="1" sequence="1" home_points="7" away_points="7"/>
        <quarter id="9a5dc1d3-112f-48f8-8e91-43e5cd956ffd" number="2" sequence="2" home_points="14" away_points="13"/>
        <quarter id="f457c21e-acc2-4ca2-8e5b-ced3ef35f189" number="3" sequence="3" home_points="3" away_points="0"/>
        <quarter id="4d1375f5-3c4d-4239-b9f2-4986ac7e2328" number="4" sequence="4" home_points="0" away_points="0"/>
      </scoring>
    </game>
    <!-- ... omitted for brevity -->
  </week>
  <!-- ... omitted for brevity -->
</season>
<!-- Generation ended @ 2026-09-01 09:00:21 +0000 -->

The response is shown trimmed to the opening game of Week 1; the JSON slice omits the per-quarter scoring.periods entries that the XML tab shows as quarter elements.

The broadcast node on each game identifies the national broadcaster in network (with satellite where applicable). Every game in a shared broadcast window carries the same network value; the field names the national broadcaster rather than regional affiliates.

When you do not need to know the season year, the Current Season Schedule returns the current season in the same shape:

GET https://api.sportradar.com/nfl/official/trial/v7/en/games/current_season/schedule.json
x-api-key: YOUR_API_KEY

3. Refresh the near-term window

To pull schedule data one week at a time, and reduce payload size compared to the entire season, use the Weekly Schedule. It returns past, current, and upcoming weeks for any available season, including venue, weather conditions, broadcast info, and scoring results by quarter. {nfl_season_week} is a zero-padded string (01 through 18):

GET https://api.sportradar.com/nfl/official/trial/v7/en/games/2025/REG/02/schedule.json
x-api-key: YOUR_API_KEY

{
    "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
                }
            }
        ]
    }
}

<?xml version="1.0" ?>
<?xml-stylesheet type="text/xsl" charset="UTF-8" href="/xslt/football/schedule-v7.0.xsl"?>
<!-- Generation started @ 2026-09-01 09:09:44 +0000 -->
<season xmlns="http://feed.elasticstats.com/schema/football/schedule-v7.0.xsd" id="fbe26310-feb8-11ef-a86e-d5de4289b45b" year="2025" type="REG" name="REG">
  <week id="efb8dd84-bdba-4136-b518-7159a02ff8db" sequence="2" title="2">
    <game 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">
        <location lat="44.501357" lng="-88.062440"/>
      </venue>
      <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"/>
      </weather>
      <scoring home_points="27" away_points="18">
        <quarter id="4e1cfae0-4c10-4fb3-a3e4-de5405a3108d" number="1" sequence="1" home_points="7" away_points="0"/>
        <quarter id="b50d7943-4bc7-40f1-8a03-80e9c8e9aa2b" number="2" sequence="2" home_points="7" away_points="3"/>
        <quarter id="7c3f67d4-140e-4a0a-84e5-ac52ca265902" number="3" sequence="3" home_points="3" away_points="0"/>
        <quarter id="31bb26f8-1cde-496d-8e60-ecb8eacb6acb" number="4" sequence="4" home_points="10" away_points="15"/>
      </scoring>
    </game>
    <!-- ... omitted for brevity -->
  </week>
</season>
<!-- Generation ended @ 2026-09-01 09:09:44 +0000 -->

The response is shown trimmed to the Thursday night game; the optional title field names showcase games such as Thursday Night Football.

During the season, the Current Week Schedule keeps the active window fresh without tracking week numbers; it returns the week in play in the same week shape:

GET https://api.sportradar.com/nfl/official/trial/v7/en/games/current_week/schedule.json
x-api-key: YOUR_API_KEY

The following is an example of how you can display a weekly schedule on your platform, showcasing key details such as team names and quarterly and final scores for past games. Club marks are placeholders for your own or licensed assets:

WEEK 2 RESULTS2025 REG · WEEK 2

WASWashington CommandersFINAL0301518

GBGreen Bay Packers7731027

LALos Angeles RamsFINAL73101333

TENTennessee Titans0133319

SEASeattle SeahawksFINAL7071731

PITPittsburgh Steelers680317

Scores populate in the schedule feeds at complete; quarter splits ride scoring.periods.

📸
Accessing Headshots and Team Logos
To access team logos and player headshots, use the Images API.

4. Read scores from the schedule

Game and period scores populate in the schedule feeds when a game reaches complete; quarter splits ride scoring.periods (the quarter elements under scoring in XML). For a scores view, the schedule alone is enough; reserve the game feeds on the Tracking Live Games page for live windows and drive-level detail.

5. Pull the Tournament Schedule

The Tournament Schedule provides the date, time, location, and other event details for every matchup taking place in a given tournament, keyed by the tournament ID from the Tournament List:

GET https://api.sportradar.com/nfl/official/trial/v7/en/tournaments/d128603c-516d-4814-83bf-b14085503e1a/schedule.json
x-api-key: YOUR_API_KEY

{
  "id": "d128603c-516d-4814-83bf-b14085503e1a",
  "name": "NFL Playoffs",
  "location": "New Orleans, LA, USA",
  "status": "scheduled",
  "league": {
    "id": "3c6d318a-6164-4290-9bbc-bf9bb21cc4b8",
    "name": "National Football League",
    "alias": "NFL"
  },
  "season": {
    "id": "26a6a4e0-dfc9-11ee-8f7c-27de425212d4",
    "year": 2024,
    "type": "PST"
  },
  "rounds": [
    {
      "id": "ea9de897-45d5-42f6-8d6b-98fab83c7a57",
      "sequence": 1,
      "name": "Wild Card Round",
      "games": [
        {
          "id": "6b71f468-5099-48ab-8957-e64d90f09857",
          "title": "Wild Card",
          "status": "scheduled",
          "coverage": "full",
          "game_type": "playoff",
          "scheduled": "2025-01-12T21:30:00+00:00",
          "entry_mode": "LDE",
          "conference_game": true,
          "home": {
            "name": "Team TBD",
            "alias": "TBD",
            "id": "23ed0bf0-f058-11ee-9989-93cc4251593a"
          },
          "away": {
            "name": "Team TBD",
            "alias": "TBD",
            "id": "23ed0bf0-f058-11ee-9989-93cc4251593a"
          }
        }
      ]
    }
  ]
}

The response is shown trimmed to the first Wild Card matchup. Matchups carry Team TBD placeholders until the regular season concludes and playoff berths are finalized, at which point home and away fill in with the team names and IDs. For tracking tournaments and building brackets, see the Tracking Playoffs integration scenario.

6. Reconcile deletions and reschedules

When a game is removed from coverage (for example, a duplicate or erroneously created game), it stays visible so that you can reconcile it:

The game remains available in game-level feeds (Boxscore, Play-by-Play, Roster, Statistics) with a deleted: true flag.
Season and Weekly Schedule responses carry a top-level deleted_games array listing the IDs of games deleted from that schedule.
The Daily Change Log adds a deleted_games node on days when a deletion occurs.

A schedule response with deletions lists the affected game IDs alongside the weeks (trimmed here to the schedule header):

{
  "id": "89049eb0-09b4-11f0-8353-5d9d7165e3e8",
  "year": 2025,
  "type": "PST",
  "name": "PST",
  "deleted_games": [
    {
      "id": "791e392f-1cc7-485c-bb95-026ac2cc31d1"
    },
    {
      "id": "03ec8add-64a4-463d-a9ee-22af5b21f6a5"
    }
  ]
}

The deleted game itself keeps serving from game-level feeds with the flag set (trimmed to the game header):

{
  "id": "791e392f-1cc7-485c-bb95-026ac2cc31d1",
  "status": "scheduled",
  "scheduled": "2026-03-24T10:00:00+00:00",
  "game_type": "regular",
  "deleted": true
}

To keep your system consistent:

Store deleted game IDs so downstream processing (statistics, standings, displays) suppresses them rather than treating a previously ingested game as still active.
Reconcile the deleted_games array against your stored games on each schedule pull.
A postponed game keeps its ID and status; its makeup game arrives under a new game ID, so match the makeup by teams and week and keep re-pulling the affected week until it appears (the status flows are on the Game Status Workflow page).

7. Watch the Daily Change Log for schedule changes

The Daily Change Log lists IDs and timestamps for schedules, teams, players, results, and game stats that were modified on a given date, so you can pick up schedule changes without re-pulling every week. For this scenario, act on the game entries and the deleted_games node: refetch the Weekly Schedule for each week that carries a changed game, and apply the deletion handling from step 6. The feed's mechanics, entity types, and polling cadence are on the Monitoring Data Changes page.

Common Use Cases

Season view: Season Schedule once, refreshed on the Update Frequencies cadence
This week's slate: Current Week Schedule on a timer
Scores ticker: Current Week Schedule plus status-driven game-feed polling during game windows, as described on the Tracking Live Games page
Postseason bracket: Tournament Schedule with the Tracking Playoffs page

Best Practices

Key stored games by ID and update rows in place; never key on kickoff time or matchup
Reconcile deleted_games on every Season or Weekly Schedule pull, and suppress deleted IDs downstream
Treat time-tbd and flex-schedule kickoff times as provisional
Let the Daily Change Log drive off-cycle refreshes so you capture schedule changes without making unnecessary calls; see Monitoring Data Changes
Depending on the endpoint, schedule data may update hourly or in real time; the Update Frequencies page carries the recommended pull interval for each schedule feed, so align your polling with it