F1 Live Timing Streamer

An Apify Actor that connects to the official Formula 1 live timing SignalR feed and streams real-time telemetry, timing data, and derived analytics to Apify's Dataset.

Features

• Real-time SignalR connection to the official F1 timing endpoint with automatic reconnection and exponential backoff
• Three output formats: raw JSON, flat SQL-ready schemas, or ML-ready timeseries
• Derived micro-metrics computed on the fly: pit time breakdowns, tire degradation projections, sector deltas
• Webhook notifications for high-value events: pit entries, flag changes, lead changes, fastest laps, DRS changes
• Safety Car filtering for clean ML training data

Quick Start

Deploy to Apify

1. Push this repository to Apify using the Apify CLI:

   $apify push
   

2. Configure the input in the Apify Console (see Input Configuration)
3. Start the Actor during a live F1 session

Run Locally

pip install -r requirements.txt
export APIFY_TOKEN=your_token_here
python main.py

Input Configuration

Parameter	Type	Default	Description
websocket_url	string	https://livetiming.formula1.com/signalr	F1 SignalR endpoint base URL
output_format	string	"raw"	Output format: raw, flat, or timeseries
enable_metrics	boolean	true	Compute derived micro-metrics
webhook_url	string	—	URL for event webhook POST notifications
webhook_events	string[]	[] (all)	Filter which events trigger webhooks
exclude_sc_laps	boolean	true	Tag SC/VSC/red flag laps as invalid in timeseries mode
log_level	string	"INFO"	Logging verbosity: DEBUG, INFO, WARNING, ERROR

Output Formats

Raw (default)

Parsed F1 events as JSON objects. Each object has a topic field indicating its type:

{
  "topic": "TimingData",
  "driver_id": "1",
  "timestamp": "2025-03-16T14:32:01+00:00",
  "position": 1,
  "last_lap_time": "1:31.456",
  "sector_0_time": "28.123",
  "sector_1_time": "34.567",
  "sector_2_time": "28.766",
  "gap_to_leader": null,
  "in_pit": false,
  "lap_number": 42
}

Flat (SQL-ready)

Events decomposed into relational rows, each with a _table field for routing to SQL tables:

Tables: laps, sectors, positions, telemetry, track_events, weather, stints, metrics, pit_stops

{
  "_table": "laps",
  "timestamp": "2025-03-16T14:32:01+00:00",
  "driver_id": "1",
  "lap_number": 42,
  "lap_time_ms": 91456.0,
  "sector_1_ms": 28123.0,
  "sector_2_ms": 34567.0,
  "sector_3_ms": 28766.0,
  "compound": "MEDIUM",
  "is_personal_best": false,
  "is_overall_fastest": false,
  "track_status": "GREEN"
}

Timeseries (ML-ready)

Normalized metric-per-row format optimized for machine learning pipelines:

{
  "_table": "timeseries",
  "timestamp": "2025-03-16T14:32:01+00:00",
  "driver_id": "1",
  "metric": "speed",
  "value": 312.5,
  "lap_number": 42,
  "compound": "MEDIUM",
  "track_status": "GREEN",
  "is_valid_lap": true
}

Metrics emitted: speed, throttle, brake, gear, drs, sector_1_time, sector_2_time, sector_3_time, lap_time, gap_to_leader

Laps under Safety Car, VSC, or red flags are tagged is_valid_lap: false when exclude_sc_laps is enabled, so ML pipelines can filter anomalous data without manual scrubbing.

Derived Micro-Metrics

When enable_metrics is true, these are computed in real-time and pushed alongside primary data:

Pit Time Breakdown

{
  "topic": "Metric",
  "metric_type": "pit_time",
  "driver_id": "1",
  "lap_number": 25,
  "pit_total_ms": 23456.0,
  "pit_stationary_ms": 2500.0,
  "pit_transit_ms": 20956.0
}

Tire Cliff Projection

Rolling 5-lap average of lap time degradation over the current stint (green-flag laps only):

{
  "topic": "Metric",
  "metric_type": "tire_cliff",
  "driver_id": "1",
  "lap_number": 30,
  "compound": "SOFT",
  "stint_lap_count": 12,
  "tire_degradation_per_lap_ms": 85.3,
  "rolling_window": 5
}

Sector Delta vs. Personal Best

{
  "topic": "Metric",
  "metric_type": "sector_delta",
  "driver_id": "1",
  "sector": 2,
  "lap_number": 42,
  "sector_time_ms": 34567.0,
  "personal_best_ms": 34123.0,
  "delta_ms": 444.0
}

Webhooks

Configure webhook_url and optionally webhook_events to receive HTTP POST notifications for high-value race events.

Supported Event Types

Event	Trigger
pit_entry	Driver enters the pit lane
pit_exit	Driver exits the pit lane
flag_change	Track status changes (green/yellow/SC/VSC/red)
lead_change	P1 position changes hands
fastest_lap	New overall fastest lap set
drs_enabled	DRS zones activated
drs_disabled	DRS zones deactivated

Webhook Payload

{
  "event_type": "lead_change",
  "timestamp": "2025-03-16T14:45:00+00:00",
  "data": {
    "new_leader": "4",
    "previous_leader": "1",
    "lap_number": 38
  }
}

Webhook delivery is async with a 5-second timeout. Failed deliveries are logged but never block the main data stream.

Architecture

F1 SignalR Feed
      │
      ▼
┌─────────────┐
│  f1client   │  SignalR negotiate → connect → subscribe → listen
│             │  Exponential backoff reconnection (max 10 retries)
└──────┬──────┘
       │ on_message callback
       ▼
┌──────────────┐
│ msg_parser   │  Decompress .z topics, parse by type, safe field access
└──────┬───────┘
       │ typed event dicts
       ▼
┌──────────────┐     ┌─────────────┐
│ driver_state │────▶│   metrics   │  Pit time, tire cliff, sector delta
└──────┬───────┘     └─────────────┘
       │
       ├──▶ schemas.py (flat mode)     → SQL-ready rows
       ├──▶ timeseries.py (ts mode)    → ML-ready rows
       └──▶ webhooks.py               → HTTP POST on events
       │
       ▼
  Apify Dataset

File Structure

File	Purpose
main.py	Apify Actor entry point and orchestration
f1client.py	SignalR client with reconnection logic
message_parser.py	Message parsing, decompression, and routing
driver_state.py	Per-driver state tracking and micro-metrics
schemas.py	Flat SQL-ready schema definitions
timeseries.py	ML-ready timeseries normalization
webhooks.py	Event detection and webhook delivery
actor.json	Apify Actor configuration and input schema
Dockerfile	Container definition (Python 3.11-slim)