Pulling Schedules

This integration scenario explains how to retrieve MLB schedules using the Sportradar MLB API. It focuses on discovering seasons, selecting the correct schedule feed for your use case, and understanding how schedule data connects to downstream game and statistics feeds.

This scenario is commonly used to:

• Build season calendars
• Display upcoming and completed games
• Discover game.id values for use in live or historical game data integrations

Overview

In the MLB API, schedules serve as the entry point for most integrations. Before accessing live play-by-play, box scores, standings, or historical statistics, applications should first retrieve schedule data to identify available seasons and games.

Before You Start: Schedule Timing and Updates

MLB schedules are typically published in the summer prior to the start of the regular season, though updates may occur throughout the year.

Common reasons schedule data may change include:

• Weather delays, postponements, and reschedules
• Doubleheader adjustments
• Postseason series updates (including if-necessary games)
• Venue or broadcast changes

💡

Best Practice

Refresh schedule data according to its update frequency to ensure the latest updates are captured.

Before requesting schedule data for a season year, use the Seasons feed to confirm which seasons are currently supported.

Relevant Feeds

The following feeds are used when pulling MLB schedules:

High-Level Workflow

A typical schedule integration follows this flow:

Seasons → Schedule → Game IDs → Downstream Feeds

1. Identify available seasons and season types
2. Retrieve the season schedule (or daily schedule)
3. Extract game.id values
4. Use game IDs for live or historical game data

Integration Steps

1. Discover Available Seasons

Start by calling the Seasons feed to determine which season years and season types are available.

GET https://api.sportradar.com/mlb/{access_level}/v8/{language_code}/league/seasons.{format}

This ensures your application only requests data for supported years and helps you select the correct season_year and season_type.

Why this matters

• Season availability can vary across products and historical depth
• Prevents invalid schedule requests for unsupported years
• Establishes the baseline for current and historical scheduling

2. Retrieve Schedule Data

Choose the schedule feed that best matches your workflow:

• Use League Schedule when you need the complete schedule for a season.

• Use Daily Schedule when you only need games for a single day.

• Use Daily Summary when you need a schedule plus context, such as:

  • Team lineups
  • Team and player statistics
  • Game-level metadata for a specific day

• Use Series Schedule during the postseason to understand series structure, participants, and if-necessary games.

Example: League Schedule

GET https://api.sportradar.com/mlb/{access_level}/v8/{language_code}/games/{season_year}/{season_type}/schedule.{format}

<league xmlns="http://feed.elasticstats.com/schema/baseball/v8/schedule.xsd" alias="MLB" name="Major League Baseball" id="2fa448bc-fc17-4d3d-be03-e60e080fdc26">
  <season-schedule id="d8c3c9ac-8002-4e1f-be49-8ad3958550d0" year="2026" type="REG">
    <games>
      <game id="fffbffca-9da3-4f35-870b-71075d9114bd" status="scheduled" coverage="full" game_number="1" day_night="N" scheduled="2026-07-31T01:40:00+00:00" home_team="d52d5339-cbdd-43f3-9dfa-a42fd588b9a3" away_team="a7723160-10b7-4277-a309-d8dd95a8ae65" double_header="false" entry_mode="STOMP" reference="823271">
        <venue name="Petco Park" market="San Diego" capacity="40222" surface="grass" address="100 Park Boulevard" city="San Diego" state="CA" zip="92101" country="USA" id="0ab45d79-5475-4308-9f94-74b0c185ee6f" field_orientation="N" stadium_type="outdoor" time_zone="US/Pacific">
          <location lat="32.70752890000001" lng="-117.1568083"/>
        </venue>
        <home name="Padres" market="San Diego" abbr="SD" id="d52d5339-cbdd-43f3-9dfa-a42fd588b9a3" win="0" loss="0"/>
        <away name="Giants" market="San Francisco" abbr="SF" id="a7723160-10b7-4277-a309-d8dd95a8ae65" win="0" loss="0"/>
      </game>
      <game id="ffefe83b-3945-4956-b2e1-779c4e3c69ae" status="scheduled" coverage="full" game_number="1" day_night="N" scheduled="2026-05-20T23:05:00+00:00" home_team="a09ec676-f887-43dc-bbb3-cf4bbaee9a18" away_team="1d678440-b4b1-4954-9b39-70afb3ebbcfa" double_header="false" entry_mode="STOMP" reference="823547">
        <venue name="Yankee Stadium" market="New York" capacity="47309" surface="grass" address="One East 161st Street" city="Bronx" state="NY" zip="10451" country="USA" id="706e9828-6687-4ac8-a409-3fb972e8bae9" field_orientation="E" stadium_type="outdoor" time_zone="US/Eastern">
          <location lat="40.8288189" lng="-73.9265691"/>
        </venue>
        <home name="Yankees" market="New York" abbr="NYY" id="a09ec676-f887-43dc-bbb3-cf4bbaee9a18" win="0" loss="0"/>
        <away name="Blue Jays" market="Toronto" abbr="TOR" id="1d678440-b4b1-4954-9b39-70afb3ebbcfa" win="0" loss="0"/>
      </game>
      <game id="ffee8cf2-1109-46a0-8dd9-133cb159553b" status="scheduled" coverage="full" game_number="1" day_night="N" scheduled="2026-09-25T23:07:00+00:00" home_team="1d678440-b4b1-4954-9b39-70afb3ebbcfa" away_team="c874a065-c115-4e7d-b0f0-235584fb0e6f" double_header="false" entry_mode="STOMP" reference="822760">
        <venue name="Rogers Centre" market="Toronto" capacity="39150" surface="turf" address="One Blue Jays Way" city="Toronto" state="ON" zip="M5V1J3" country="CAN" id="84d72338-2173-4a90-9d25-99adc6c86f4b" field_orientation="N" stadium_type="retractable" time_zone="US/Eastern">
          <location lat="43.6417388" lng="-79.3892547"/>
        </venue>
        <home name="Blue Jays" market="Toronto" abbr="TOR" id="1d678440-b4b1-4954-9b39-70afb3ebbcfa" win="0" loss="0"/>
        <away name="Reds" market="Cincinnati" abbr="CIN" id="c874a065-c115-4e7d-b0f0-235584fb0e6f" win="0" loss="0"/>
      </game>

The League Schedule feed returns:

• Scheduled start times and venues
• Game status (e.g., scheduled, inprogress, postponed, closed)
• Home/away teams and metadata (doubleheaders, day/night, broadcasts)
• Season context for the returned games

Each game includes a unique game.id, which is required for retrieving game-centric data.

3. Build Team-Specific Schedules (Optional)

While MLB does not provide a standalone “team schedule” endpoint, team schedules are built by filtering schedule data.

1. Retrieve the League Schedule for the desired season_year and season_type

2. Filter games where:

   • home_team or
   • away_team matches the desired team.id

3. Sort or group games by date for display

This image shows an example of a rendered team schedule, demonstrating how MLB schedule data can be used to display opponents, game dates, and start times for a specific team.

4. Track Schedule and Status Changes

Schedule changes occur throughout the season due to weather, operational decisions, and postseason logic.

Key fields to monitor include:

• status (e.g., scheduled, wdelay, postponed, suspended, closed)
• scheduled (start time)
• double_header, game_number
• venue and broadcasts (when applicable)

Use the Daily Change Log to detect updates without repeatedly pulling large schedule payloads.

GET https://api.sportradar.com/mlb/{access_level}/v8/{language_code}/league/{year}/{month}/{day}/changes.{format}

This helps conserve call limits while ensuring your application reflects the most current dates, start times, and statuses. Treat schedule feeds as the source of truth for timing.

5. Use Game IDs in Other Integrations

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

• Live game tracking (Play-by-Play, Game Summary, Boxscore)
• Postponed and suspended game handling
• Historical game retrieval and season statistics workflows

Your platform can then use schedule discovery as the foundation for live and historical data pipelines.

Common Use Cases

Pulling schedules supports many common integration needs, such as:

• Displaying upcoming games by date
• Showing completed games and results
• Powering scoreboard views and game detail pages
• Driving calendar-based views and notifications
• Supporting postseason series views and if-necessary logic
• Linking schedule data to live play-by-play and box score updates

Best Practices

• Call Seasons before requesting schedules for the first time
• Do not hardcode game dates, series outcomes, or IDs
• Cache schedule responses and refresh according to the update frequency
• Treat schedule feeds as the authoritative source for timing and game status
• Use game.id as the primary key for game-centric data and downstream integrations