Race Weekend Data Guide

🏎️ Motorsport API Required
This guide requires an active Motorsport API subscription (€79/mo, 3,000 API calls/hr).
View pricing →

A Formula 1 race weekend consists of multiple on-track sessions spread across three or four days. This guide explains how the Motorsport API models a race weekend, how to retrieve all sessions and their data, and how to handle the differences between standard and Sprint weekends.

What you'll learn:

How a race weekend maps to Stages and Fixtures in the API
How to retrieve a full race weekend's sessions in a single call
How to identify session types programmatically
How to fetch results for any session within a weekend

Prerequisites: Active Motorsport API subscription, API token, familiarity with REST APIs

1. How a race weekend is modelled

In the Motorsport API, a race weekend is a Stage. Each individual on-track session within that weekend - Practice 1, Qualifying, the Race - is a Fixture. This is the most important distinction to understand before building anything.

Stage: Formula 1 Louis Vuitton Australian Grand Prix 2025
├── Fixture: Practice 1        (leg: "1/3")
├── Fixture: Practice 2        (leg: "2/3")
├── Fixture: Practice 3        (leg: "3/3")
├── Fixture: Qualifying 1      (leg: "1/3")
├── Fixture: Qualifying 2      (leg: "2/3")
├── Fixture: Qualifying 3      (leg: "3/3")
└── Fixture: Race              (leg: "1/1")

A Sprint weekend replaces Practice 2 and 3 with Sprint Qualifying and a Sprint Race, and has only one practice session:

Stage: Formula 1 Heineken Chinese Grand Prix 2025
├── Fixture: Practice 1        (leg: "1/1")
├── Fixture: Sprint Qualifying 1  (leg: "1/3")
├── Fixture: Sprint Qualifying 2  (leg: "2/3")
├── Fixture: Sprint Qualifying 3  (leg: "3/3")
├── Fixture: Sprint Race       (leg: "1/1")
├── Fixture: Qualifying 1      (leg: "1/3")
├── Fixture: Qualifying 2      (leg: "2/3")
├── Fixture: Qualifying 3      (leg: "3/3")
└── Fixture: Race              (leg: "1/1")

On a Sprint weekend, Practice 1 returns leg: "1/1" because it is the only practice session. Do not use leg alone to identify session type - use the metadata include with the IS_QUALIFICATION, SPRINT_RACE, and HAS_STANDING flags for programmatic session identification.

2. Retrieving race weekend data

Option A: Full season schedule (recommended for calendar builds)

The most efficient way to get all race weekends with their sessions and circuit data is the Schedules endpoint. It returns all stages, all fixtures, and venue metadata for the entire season in one call:

GET /v3/motorsport/schedules/seasons/25273?api_token=YOUR_TOKEN

The response nests fixtures inside stages, and venue inside each fixture. No additional includes are needed - everything is pre-embedded.

Use this approach when building a season calendar view or race weekend preview pages. Cache the response aggressively - schedule data changes infrequently. See the Schedules documentation for pagination guidance.

Option B: Single race weekend with sessions

To retrieve a specific race weekend and all its sessions:

GET /v3/motorsport/stages/STAGE_ID
?api_token=YOUR_TOKEN&include=fixtures;fixtures.state;fixtures.venue

This returns the stage with all its fixtures embedded, each enriched with their current state and circuit. Include depth on Stages endpoints is 4, so you can nest further:

GET /v3/motorsport/stages/STAGE_ID
?api_token=YOUR_TOKEN&include=fixtures;fixtures.state;fixtures.venue;fixtures.metadata

Option C: Sessions by date range

To retrieve all sessions across a race weekend date range:

GET /v3/motorsport/fixtures/between/2025-03-14/2025-03-16
?api_token=YOUR_TOKEN&include=stage;state;venue

Note: the date range endpoint has a maximum of 100 days and returns fixtures paginated. Stage dates (starting_at / ending_at) are date-only (YYYY-MM-DD), while fixture starting_at includes the time of day.

3. Identifying session types

Use the name field for human-readable session labels. For programmatic type checks, use ?include=metadata and check the session type flags:

Flag

true means

IS_QUALIFICATION

This is one of the three qualifying segments (Q1, Q2, Q3)

SPRINT_RACE

This is a Sprint Race session

HAS_STANDING

This session awards championship points

Do not parse the name field for type logic - session naming can vary and is not a stable identifier.

To get the total lap count and race distance for a race fixture:

GET /v3/motorsport/fixtures/FIXTURE_ID?api_token=YOUR_TOKEN&include=metadata

The metadata array will include TOTAL_LAPS and RACE_DISTANCE for race sessions. Resolve type IDs via the Metadata & Per-Season Data Type Reference.

4. Retrieving session results

Practice and qualifying results

For a compact result set (positions and times):

GET /v3/motorsport/fixtures/FIXTURE_ID
?api_token=YOUR_TOKEN&include=results;venue;state

For full lineup detail including driver status and fastest lap:

GET /v3/motorsport/fixtures/FIXTURE_ID
?api_token=YOUR_TOKEN&include=lineups.details;venue;state

Race results

Race results use the same endpoints. Add metadata to include total lap count and race distance alongside the result:

GET /v3/motorsport/fixtures/FIXTURE_ID
?api_token=YOUR_TOKEN&include=lineups.details;metadata;venue;state

For a complete season record of race results per driver or team, use the dedicated Race Results endpoints instead - they return all race and sprint race fixtures for the season in a single nested response.

5. Complete implementation example

The following example fetches a full race weekend - all sessions with circuit info and results - given a stage ID.

const BASE = 'https://api.sportmonks.com/v3/motorsport';
const TOKEN = 'YOUR_API_TOKEN';

async function getRaceWeekend(stageId) {
  const params = new URLSearchParams({
    api_token: TOKEN,
    include: 'fixtures;fixtures.state;fixtures.venue;fixtures.lineups.details'
  });

  const res = await fetch(`${BASE}/stages/${stageId}?${params}`);

  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  const { data } = await res.json();

  const sessions = (data.fixtures || [])
    .filter(f => !f.placeholder)
    .sort((a, b) => a.starting_at_timestamp - b.starting_at_timestamp)
    .map(f => ({
      id: f.id,
      name: f.name,
      leg: f.leg,
      starting_at: f.starting_at,
      state: f.state?.name ?? 'Unknown',
      circuit: f.venue?.name ?? 'Unknown',
      results: (f.lineups || []).map(l => ({
        driver: l.driver_name,
        number: l.driver_number
      }))
    }));

  return {
    weekend: data.name,
    round: data.sort_order,
    starts: data.starting_at,
    ends: data.ending_at,
    sessions
  };
}

import requests

BASE = 'https://api.sportmonks.com/v3/motorsport'
TOKEN = 'YOUR_API_TOKEN'

def get_race_weekend(stage_id):
    params = {
        'api_token': TOKEN,
        'include': 'fixtures;fixtures.state;fixtures.venue;fixtures.lineups.details'
    }

    res = requests.get(f'{BASE}/stages/{stage_id}', params=params, timeout=30)
    res.raise_for_status()
    data = res.json()['data']

    fixtures = data.get('fixtures', [])
    sessions = sorted(
        [f for f in fixtures if not f.get('placeholder')],
        key=lambda f: f.get('starting_at_timestamp', 0)
    )

    return {
        'weekend': data['name'],
        'round': data['sort_order'],
        'starts': data['starting_at'],
        'ends': data['ending_at'],
        'sessions': [
            {
                'id': f['id'],
                'name': f['name'],
                'leg': f['leg'],
                'starting_at': f['starting_at'],
                'state': f.get('state', {}).get('name', 'Unknown'),
                'circuit': f.get('venue', {}).get('name', 'Unknown')
            }
            for f in sessions
        ]
    }

<?php

function getRaceWeekend($stageId, $token) {
    $base = 'https://api.sportmonks.com/v3/motorsport';
    $params = http_build_query([
        'api_token' => $token,
        'include' => 'fixtures;fixtures.state;fixtures.venue;fixtures.lineups.details'
    ]);

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => "{$base}/stages/{$stageId}?{$params}",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("HTTP {$httpCode}: Request failed");
    }

    $data = json_decode($response, true)['data'];
    $fixtures = array_filter(
        $data['fixtures'] ?? [],
        fn($f) => !$f['placeholder']
    );

    usort($fixtures, fn($a, $b) => $a['starting_at_timestamp'] - $b['starting_at_timestamp']);

    return [
        'weekend' => $data['name'],
        'round' => $data['sort_order'],
        'starts' => $data['starting_at'],
        'ends' => $data['ending_at'],
        'sessions' => array_map(fn($f) => [
            'id' => $f['id'],
            'name' => $f['name'],
            'leg' => $f['leg'],
            'starting_at' => $f['starting_at'],
            'state' => $f['state']['name'] ?? 'Unknown',
            'circuit' => $f['venue']['name'] ?? 'Unknown'
        ], array_values($fixtures))
    ];
}
?>

6. Common pitfalls

Confusing Stage ID and Fixture ID

Both stages and fixtures have numeric IDs. Passing a fixture ID to a stages endpoint (or vice versa) will return a 404. Always confirm which ID you have before making a request. If you retrieved the ID from a schedule response, check whether the object has a fixtures array (stage) or a stage_id field (fixture).

Not filtering placeholder fixtures

Fixtures are created before timing is confirmed. A placeholder: true fixture has a session type but no confirmed start time. Always filter placeholder === false when displaying schedules to users.

Assuming Practice 1 is always leg: "1/3"

On Sprint weekends Practice 1 is the only practice session, so it returns leg: "1/1". Do not use leg to count sessions or infer weekend type - use the metadata flags instead.

Using starting_at on stages for time-of-day

Stage starting_at and ending_at are date-only strings (YYYY-MM-DD). They do not include a time component. For session start times with time of day, read starting_at from the individual fixture objects.

Sorting by starting_at string instead of starting_at_timestamp

Always sort fixtures by starting_at_timestamp (a Unix integer) rather than the starting_at string. String sorting on datetime values can produce incorrect order when timezones or formats vary.

Stages - Race weekend data
Fixtures - Individual session data
Schedules - Full season calendar in one call
Race Results - Season-level results per driver or team
States - All possible fixture states
Data Model - Full entity hierarchy
Metadata & Per-Season Data Type Reference
Results & Live Data Type Reference

8. FAQ

Q: How do I know if a race weekend is a Sprint weekend?

Fetch the stage with ?include=fixtures and check whether any fixture has name containing "Sprint". More reliably, fetch a fixture with ?include=metadata and check the SPRINT_RACE flag.

Q: Why does my schedule response show fixtures with result_info: null?

result_info is only populated after a session completes. For upcoming or in-progress sessions it is always null. Use ?include=state to check session status and ?include=lineups.details for live or post-session results.

Q: What is the difference between results and lineups.details?

results returns a compact subset: position, time, interval, gap to leader, and tyre. lineups.details returns the full set including points scored, grid position, lap count, pitstop count, driver status (DNS/DNF/DSQ), fastest lap, and the live in_pit indicator. Use results for summary cards and lineups.details for detailed race reports.

Q: How do I get the circuit for a race weekend?

Use ?include=fixtures.venue on the stage, or ?include=venue directly on any fixture within the stage. All fixtures in the same stage share the same venue_id. The Schedules endpoint embeds venue data automatically.

Q: Is this available in all subscription plans?

All Motorsport API endpoints require an active Motorsport API subscription (€79/mo). View pricing →

Last updated 1 month ago

Was this helpful?