# Race Weekend Data Guide

> **🏎️ Motorsport API Required**
>
> This guide requires an active Motorsport API subscription (€79/mo, 3,000 API calls/hr).
>
> [View pricing →](https://www.sportmonks.com/formula-one-api/)

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:

```http
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](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/schedules) documentation for pagination guidance.

#### Option B: Single race weekend with sessions

To retrieve a specific race weekend and all its sessions:

```http
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:

```http
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:

```http
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:

```http
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](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference).

### 4. Retrieving session results

#### Practice and qualifying results

For a compact result set (positions and times):

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

For full lineup detail including driver status and fastest lap:

```http
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:

```http
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](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/race-results) 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.

{% tabs %}
{% tab title="Javascript" %}

```javascript
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
  };
}
```

{% endtab %}

{% tab title="Python" %}

```python
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
        ]
    }
```

{% endtab %}

{% tab title="PHP" %}

```php
<?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))
    ];
}
?>
```

{% endtab %}
{% endtabs %}

### 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.

### 7. Related features

* [Stages](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/stages) - Race weekend data
* [Fixtures](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/fixtures) - Individual session data
* [Schedules](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/schedules) - Full season calendar in one call
* [Race Results](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/race-results) - Season-level results per driver or team
* [States](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/states) - All possible fixture states
* [Data Model](https://docs.sportmonks.com/v3/motorsport-api/welcome/data-model) - Full entity hierarchy
* [Metadata & Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference)
* [Results & Live Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-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 →](https://www.sportmonks.com/formula-one-api/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/race-weekend-data-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.