Pulling Schedules

This scenario explains how to build a Formula 1 schedule: the season calendar, each Grand Prix, and the individual sessions (practice, qualifying, sprint, and race) within a weekend, along with circuit details.

This is commonly used to:

• Build a season calendar and an event-weekend timetable
• Show session start times in the user's local time zone
• Discover the stage IDs you will pass to every other feed

Relevant Feeds

High-Level Workflow

Seasons → Stage Schedule → Store stage IDs → Display calendar

1. Get the target season's stage ID from Seasons.
2. Request Stage Schedule for that season to get every event and session.
3. Store the stage IDs and unique_stage_id values for subsequent calls.
4. Display the calendar and refresh when the schedule changes.

1. Get the Season Stage ID

Call Seasons and pick the season you want. Authentication is the x-api-key header on every request; see API Basics.

GET https://api.sportradar.com/formula1/trial/v2/en/seasons.json
x-api-key: YOUR_API_KEY

{
  "stages": [
    {
      "id": "sr:stage:1189123",
      "description": "Formula 1 2025",
      "scheduled": "2025-03-14T01:35:00+00:00",
      "scheduled_end": "2025-12-07T15:00:00+00:00",
      "type": "season",
      "category": { "id": "sr:category:36", "name": "Formula 1" },
      "sport": { "id": "sr:sport:40", "name": "Formula 1" },
      "single_event": false,
      "gender": "men"
    }
  ]
}

Keep the id (sr:stage:1189123); it is the stage ID for the 2025 season.

2. Get the Season's Events and Sessions

Pass the season stage ID to Stage Schedule. The response lists every event as a stage, with its sessions nested inside and each session carrying its own stage ID.

GET https://api.sportradar.com/formula1/trial/v2/en/sport_events/sr:stage:1189123/schedule.json
x-api-key: YOUR_API_KEY

{
  "stages": [
    {
      "id": "sr:stage:1189125",
      "description": "Australian Grand Prix 2025",
      "scheduled": "2025-03-14T01:30:00+00:00",
      "scheduled_end": "2025-03-16T06:00:00+00:00",
      "type": "event",
      "status": "Closed",
      "unique_stage_id": "sr:stage_unique:1",
      "venue": {
        "id": "sr:venue:1011",
        "name": "Albert Park Circuit",
        "city": "Melbourne",
        "country": "Australia",
        "country_code": "AUS",
        "length": 5278,
        "laps": 58,
        "curves_left": 5,
        "curves_right": 9,
        "debut": 1996,
        "timezone": "Australia/Melbourne"
      },
      "stages": [
        { "id": "sr:stage:1189127", "description": "Practice 1", "type": "practice", "status": "Closed", "scheduled": "2025-03-14T01:30:00+00:00" },
        { "id": "sr:stage:1189129", "description": "Practice 2", "type": "practice", "status": "Closed", "scheduled": "2025-03-14T05:00:00+00:00" },
        { "id": "sr:stage:1189131", "description": "Practice 3", "type": "practice", "status": "Closed", "scheduled": "2025-03-15T01:30:00+00:00" },
        {
          "id": "sr:stage:1189133",
          "description": "Qualification",
          "type": "qualifying",
          "status": "Closed",
          "scheduled": "2025-03-15T05:00:00+00:00",
          "stages": [
            { "id": "sr:stage:1189141", "description": "Q1", "type": "qualifying_part" },
            { "id": "sr:stage:1189143", "description": "Q2", "type": "qualifying_part" },
            { "id": "sr:stage:1189145", "description": "Q3", "type": "qualifying_part" }
          ]
        },
        { "id": "sr:stage:1189139", "description": "Race", "type": "race", "status": "Closed", "scheduled": "2025-03-16T04:00:00+00:00" }
      ]
    }
  ]
}

The full feed returns all events in the season; the excerpt shows one. Sprint weekends add a sprint_race session and a "Sprint Qualifying" session, as covered in Tracking Live Races.

3. Read Circuit and Timing Details

Each event carries a venue object with circuit metadata (name, city, country, length in metres, laps, corner counts, debut year, and timezone). Every scheduled timestamp is UTC; convert to local time using the venue timezone (for example Australia/Melbourne) for a weekend timetable. See API Basics on dates and times.

scheduled and scheduled_end describe the scheduled (broadcast) window, not the actual on-track start and finish. To record when a session actually ended, capture a timestamp when its status first becomes Finished (see Race Status Workflow).

Refresh Strategy

• Schedules change rarely; poll daily, and hourly during an event weekend to catch session-time changes and cancellations.
• Store each event's unique_stage_id so you can match the same Grand Prix across seasons. See ID Handling.
• Watch the event and session status to know when to switch a session from schedule display to live timing.

Errors

• Authentication failures return 403 with an HTML body; branch on the status code. See API Basics.
• Rate-limit errors return 429; slow your request rate and retry.

Best Practices

• Treat Seasons as the entry point; never hardcode a season stage ID.
• Cache the schedule and refresh on a cadence (see Update Frequencies), not on every page view.
• Drive UI state off the type and status attributes, not the localized description.