Pulling Schedules

This integration scenario explains how to retrieve NASCAR schedules using the Sportradar NASCAR API. It focuses on discovering seasons, identifying race events, and understanding how schedule data connects to downstream race and leaderboard feeds.

This scenario is commonly used to:

Build season calendars
Display upcoming and completed races
Discover race.id values for use in live or historical race data integrations

Overview

In the NASCAR API, schedules serve as the entry point for most integrations. Before accessing live race data, standings, or historical statistics, applications should first retrieve schedule data to identify available seasons and races.

Before You Start: Schedule Timing and Updates

NASCAR schedules are finalized in stages and may change throughout the season.

Season race schedules are typically published shortly after the previous season ends, often within the following week.
Practice and qualifying schedules are finalized later, usually closer to the start of the season (often around January).

Schedule updates:

Can occur at any time during the season
May affect race times, practice, or qualifying sessions
Are not limited to specific days or periods

The scheduling process is consistent across all NASCAR series, even though exact timing may vary by season.

💡
Best Practice
Refresh schedule data according to its update frequency to ensure the latest updates are captured.
Before requesting schedule data, use the Seasons feed to confirm which seasons are currently supported.
This is especially important when accessing future seasons, as schedule data is only available once a season appears in the Seasons feed.

Relevant Feeds

The following feeds are used when pulling NASCAR schedules:

Feed	Purpose
Seasons	Discover available seasons for a series
Schedule	Retrieve full regular-season schedules
Playoff Schedule	Retrieve playoff race schedules. See the NASCAR Playoffs scenario.
Daily Change Log	Detect when schedule-related updates occur

High-Level Workflow

A typical schedule integration follows this flow:

Seasons → Schedule → Race IDs → Downstream Feeds

Identify available seasons
Retrieve the season schedule
Extract race.id values
Use race IDs for live or historical race data

Integration Steps

1. Discover Available Seasons

Start by calling the Seasons feed to determine which seasons are available for the desired NASCAR series.

GET https://api.sportradar.com/nascar-ot3/series/list.json

This ensures your application only requests data for supported years.

Why this matters

Not all series may have the same historical depth
Prevents unnecessary or invalid feed requests
Establishes your baseline for historical and current data

2. Retrieve the Season Schedule

Once the season is selected, call the Schedule feed using the appropriate season_year and series parameters.

GET https://api.sportradar.com/nascar-ot3/mc/2026/races/schedule.json

<series xmlns="http://feed.elasticstats.com/schema/nascar/schedule-v3.0.xsd" id="3e32047e-4ff3-4e35-a607-1546a2c32214" alias="CUP" name="NASCAR Cup Series">
  <season year="2026" id="2e2bfe7c-f9c2-4009-b9b4-f4511bac7a77">
    <event id="524cb97a-bdc9-413b-976c-a1470494344a" name="NASCAR Cup Series at Bowman Gray" start_date="2026-02-01">
      <track name="Bowman Gray Stadium" market="Winston-Salem" completed="1947" distance="0.25" shape="Oval" banking="Turns: 4" address="1250 S Martin Luther King Jr Dr" city="Winston-Salem" state="NC" zip="27107" country="USA" surface="Paved" track_type="Short Track" owner="International Speedway Corp." id="8dbdf7bb-2ee0-4f06-9a1c-e2c93aa715a0" lng="-80.222061" lat="36.083221"/>
      <race id="38125d3a-ade5-416b-a570-6a27ce0b0ec1" name="NASCAR Clash Heat Race 1" status="scheduled" distance="6" laps="25" chase_race="false" heat_race="true" award_pole="false" stage_count="0" scheduled="2026-02-01T01:30:00+00:00">
        <broadcast network="FOX" satellite="219" radio="MRN"/>
        <prior_winner first_name="Chase" last_name="Elliott" full_name="Chase Elliott" id="5fd3e3fb-322f-4157-ae41-9317fba1997d"/>
      </race>
      <race id="0331d465-9df1-429e-8cc3-bf9c021532a5" name="NASCAR Clash Heat Race 2" status="scheduled" distance="6" laps="25" chase_race="false" heat_race="true" award_pole="false" stage_count="0" scheduled="2026-02-01T01:45:00+00:00">
        <broadcast network="FS1" satellite="219" radio="MRN"/>
        <prior_winner first_name="Chris" last_name="Buescher" full_name="Chris Buescher" id="25cfebb6-24e5-429c-a9db-c276bab0e228"/>
      </race>
      <race id="a93d7c95-523d-4178-82ea-6f95b01169c5" name="NASCAR Clash Heat Race 3" status="scheduled" distance="6" laps="25" chase_race="false" heat_race="true" award_pole="false" stage_count="0" scheduled="2026-02-01T02:00:00+00:00">
        <broadcast network="FS1" satellite="219" radio="MRN"/>
        <prior_winner first_name="Denny" last_name="Hamlin" full_name="Denny Hamlin" id="cb9d6f49-0044-4305-be9a-22d428e52c95"/>
      </race>
      <race id="6e75b95e-98f0-49e9-8b9e-67031da0488e" name="NASCAR Clash Heat Race 4" status="scheduled" distance="6" laps="25" chase_race="false" heat_race="true" award_pole="false" stage_count="0" scheduled="2026-02-01T02:15:00+00:00">
        <broadcast network="FS1" satellite="219" radio="MRN"/>
        <prior_winner first_name="Tyler" last_name="Reddick" full_name="Tyler Reddick" id="b030a8df-e7de-44a4-9f59-34bb9fd227d0"/>
      </race>
      <race id="5a0416f0-7781-408f-a540-24df00be64e5" name="NASCAR Clash Last Chance Qualifying Race" status="scheduled" distance="18" laps="75" chase_race="false" heat_race="true" award_pole="false" stage_count="0" scheduled="2026-02-01T23:00:00+00:00">
        <broadcast network="FS1" satellite="219" radio="MRN"/>
      </race>
      <race id="16adca48-2c79-49f7-82c3-0a06fd46e5c4" name="NASCAR Clash at Bowman Gray" status="scheduled" distance="50" laps="200" chase_race="false" heat_race="false" award_pole="false" stage_count="0" parent_id="c954e475-01b2-4891-8682-67ff5f815d7a" scheduled="2026-02-02T01:00:00+00:00" start_time="2026-02-02T01:00:00+00:00">
        <practice sequence="1" status="scheduled" start_time="2026-01-31T23:10:00+00:00"/>
        <broadcast network="FOX" radio="MRN"/>
        <prior_winner first_name="Chase" last_name="Elliott" full_name="Chase Elliott" id="5fd3e3fb-322f-4157-ae41-9317fba1997d"/>
      </race>
    </event>
    <event id="80f542ce-802c-4a7d-9738-4a9eb56dd160" name="NASCAR Cup Series at Daytona" start_date="2026-02-12">
      <track name="Daytona International Speedway" market="Daytona Beach" completed="1958" distance="2.5" shape="Tri-Oval" banking="Turns: 31, Tri-Oval: 18, Backstretch: 3" frontstretch="3800" backstretch="3000" address="1801 West International Speedway Blvd." city="Daytona Beach" state="Florida" zip="32114-1243" country="USA" surface="Paved" track_type="Superspeedway" owner="International Speedway Corp." id="6ff97f68-2e9d-4fe6-8cd8-2969e1d3570b" lng="-81.067" lat="29.192994"/>
      <race id="e2672696-a1c9-48cc-b7bc-977336eddf33" name="Duel 1 at DAYTONA" status="scheduled" distance="150" laps="60" chase_race="false" heat_race="false" award_pole="false" stage_count="0" parent_id="52a541f7-db54-4c5f-a7f3-9f7097af26df" scheduled="2026-02-13T00:00:00+00:00">
        <broadcast network="FS1" satellite="668" radio="MRN"/>
        <prior_winner first_name="Bubba" last_name="Wallace" full_name="Bubba Wallace" id="939e647d-756f-41d7-ad65-609344f64bd5"/>
      </race>
      <race id="4b503455-839b-47cb-a68b-d75e75649550" name="Duel 2 at DAYTONA" status="scheduled" distance="150" laps="60" chase_race="false" heat_race="false" award_pole="false" stage_count="0" parent_id="52a541f7-db54-4c5f-a7f3-9f7097af26df" scheduled="2026-02-13T01:45:00+00:00">
        <broadcast network="FS1" satellite="668" radio="MRN"/>
      </race>
      <race id="5fb60476-dd14-4efd-821a-dbc4656d58cb" name="DAYTONA 500" status="scheduled" number="1" distance="500" laps="200" chase_race="false" heat_race="false" award_pole="true" stage_count="2" stage_1_laps="65" stage_2_laps="65" stage_3_laps="100" parent_id="a3dad4fc-112f-4aff-a261-c918182f7a42" scheduled="2026-02-15T19:30:00+00:00" start_time="2026-02-15T19:30:00+00:00">
        <practice sequence="1" status="scheduled" start_time="2026-02-11T15:00:00+00:00"/>
        <practice sequence="2" status="scheduled" start_time="2026-02-13T22:35:00+00:00"/>
        <practice sequence="3" status="scheduled" start_time="2026-02-14T20:00:00+00:00"/>
        <qualifying start_time="2026-02-12T01:15:00+00:00" status="scheduled"/>
        <broadcast network="FOX" radio="MRN"/>
        <prior_winner first_name="William" last_name="Byron" full_name="William Byron" id="c9bf58a8-66b6-4d75-a441-c13130ded990"/>
      </race>
    </event>

The Schedule feed returns:

Events and races
Scheduled start dates and times
Race status (scheduled, in progress, closed)
Track details
Broadcast metadata
Session timing for practice and qualifying (when applicable)

Each race includes a unique race.id, which is required for retrieving race-specific data.

3. Understand Events vs. Races

Within the Schedule feed:

Events group related on-track activity at a venue
Races represent individual competitive sessions

Some events may contain multiple races, such as:

Qualifying or heat races
Exhibition or non-points races
Doubleheader or special-format events

Your integration should iterate through all race objects within each event to ensure no races are missed.

4. Track Schedule and Status Changes

Race schedules can change due to weather, operational decisions, or broadcast adjustments.

Key fields to monitor include:

status (scheduled, inprogress, delayed, closed)
scheduled, start_time, and end_time

Use the Daily Change Log to track updates to schedule-related fields, and poll the Schedule feed according to its update frequency.

GET https://api.sportradar.com/nascar-ot3/2025/01/06/changes.json

This helps conserve call limits while ensuring your application reflects the most current dates and start times. The Schedule feed should always be treated as the source of truth.

5. Use Race IDs in Other Integrations

After retrieving the schedule, store or cache each race.id for use in other scenarios, including:

This allows your platform to streamline schedule discovery into live and historical data workflows.

Common Use Cases

Pulling schedules supports many common integration needs, such as:

Displaying upcoming races by date
Monitor playoff schedules.
Showing completed races and results
Linking schedule data to live race updates
Powering calendar-based views or notifications
Driving race-level analytics and reporting

Best Practices

Call Seasons before requesting schedules for the first time
Do not hardcode race dates or IDs
Cache schedule responses and refresh according to the update frequency
Treat the Schedule feed as the authoritative source for timing and status
Use race.id as the primary key for race-related data