📖 OpenLiveTiming API Documentation
Table of Contents
Overview
OpenLiveTiming provides a REST API and SignalR hub for streaming live motorsport timing data. You can push race data from your own timing application and have it displayed in real-time on your dedicated live timing page.
The platform is organized around a simple hierarchy:
Account (your organization)
└─ Instance (a live timing feed, e.g. "adac-mx-masters")
└─ API Key (grants push access to specific instances)Authentication
The API supports two authentication methods for pushing data:
API Key (recommended for workers)
Use the X-Api-Key header with a key created from your
account dashboard.
X-Api-Key: rm_a1b2c3d4e5f6...
JWT Bearer Token (for user-facing operations)
Obtain a token via POST /api/auth/login:
POST /api/auth/login
Content-Type: application/json
{
"email": "you@example.com",
"password": "your-password"
}
// Response:
{
"token": "eyJhbGciOi...",
"email": "you@example.com",
"displayName": "Your Name"
}
// Use in subsequent requests:
Authorization: Bearer eyJhbGciOi...Quick Start
Step by step, with your own pages and keys when you are signed in: push your timing data with the API.
- Create your live timing at /create (or via the API).
- Create an API key from your account dashboard, scoped to your instance.
- Push a full state to initialize your timing page (see below).
- Push incremental events as the race progresses.
- View live at
olt.live/lt/your-slug, or embed it on your website.
Pushing Race Data
Full State (complete snapshot)
Push a complete race state. This is the primary way to update your timing page.
New viewers and reconnecting clients will receive this state immediately.
The snapshot goes in a state object; a new groupName or runName
starts a new session and archives the previous one as results.
POST /api/instances/{slug}/race/fullstate
X-Api-Key: your-api-key
Content-Type: application/json
{
"state": {
"session": {
"trackName": "Circuit de Spa",
"eventName": "Club Championship",
"groupName": "Race 1",
"runName": "Final",
"runType": "Race",
"flag": "Green",
"timeToGo": "00:25:00",
"laps": 5,
"totalLaps": 20,
"sectorCount": 3
},
"drivers": {
"1": {
"number": "1",
"fullName": "Max Speed",
"className": "Pro",
"position": 1,
"laps": 5,
"lastTime": "1:45.123",
"bestTime": "1:44.567",
"sectorTimes": ["32.100", "38.200", "34.823"],
"gap": "",
"interval": ""
},
"44": {
"number": "44",
"fullName": "Lewis Quick",
"className": "Pro",
"position": 2,
"laps": 5,
"lastTime": "1:45.456",
"bestTime": "1:44.890",
"gap": "+0.323",
"interval": "+0.323"
}
}
}
}
- Times:
"1:44.567","00:01:44.567"or a number of seconds (104.567). - Flags (
flag):None,Green,Yellow,Red,Blue,White,Black,Checkered,SafetyCar,VirtualSafetyCar(the name or its number). - Run types (
runType):Practice,Qualifying,Race, … (the name or its number). - Timestamp: optional (
"timestamp"next tostate, UTC); the time of arrival otherwise. - A session under the
Checkeredflag is archived 120 seconds after its last update.
Update Cache Only (no broadcast)
Use PUT instead of POST to update the cached state without broadcasting to connected viewers. Useful for high-frequency updates.
PUT /api/instances/{slug}/race/fullstate
X-Api-Key: your-api-key
Content-Type: application/json
{ "state": { ...same body... } }
Push Individual Events
Send individual race events for real-time updates (lap and best lap highlights, flag changes, the lap history of the results):
POST /api/instances/{slug}/race/event
X-Api-Key: your-api-key
Content-Type: application/json
{
"$type": "LapCompleted",
"driverNumber": "44",
"driverName": "Lewis Quick",
"lapNumber": 6,
"lapTime": "1:44.567",
"isPersonalBest": true,
"isOverallBest": false,
"position": 2
}
Push Batch Events
POST /api/instances/{slug}/race/events
X-Api-Key: your-api-key
Content-Type: application/json
[
{ "$type": "SectorCompleted", "driverNumber": "1", "driverName": "Max Speed", "sectorIndex": 0, "sectorTime": "31.900", "isPersonalBest": true, "isOverallBest": true },
{ "$type": "FlagChange", "oldFlag": "Green", "newFlag": "Yellow" }
]Race Event Types
Events use a $type discriminator for polymorphic JSON serialization:
| Type | Description |
|---|---|
SectorCompleted | A driver completed a timing sector |
LapCompleted | A driver completed a lap |
PositionChange | Driver classification position changed |
BestLap | New session overall best lap time |
BestSector | New session overall best sector time |
FlagChange | Track flag status changed (Green, Yellow, Red, etc.) |
SessionInfoUpdate | Session metadata updated |
FullState | Complete state snapshot |
Announcement | Race control announcement |
Reading Live Data & Results
The read endpoints need no API key for a public page; a private page answers to its signed-in members only, a password-protected one after the password is accepted (403 otherwise).
| Endpoint | Description |
|---|---|
GET /api/instances/{slug}/race/fullstate | Current state of the session (404 before any data) |
GET /api/instances/{slug}/race/events?since= | Buffered events since a UTC timestamp (the last hour at most) |
GET /api/instances/{slug}/race/history?limit=20 | Archived sessions, newest first (100 at most) |
GET /api/instances/{slug}/race/history/{id} | Final state of an archived session |
GET /api/instances/{slug}/race/history/{id}/laps[/{number}] | Lap and sector breakdown of an archived session (all drivers, or one) |
Every archived session of a public page also has a results page for people:
https://openlivetiming.com/lt/your-slug/results.
Real-Time via SignalR
For consuming live data in real-time, connect to the SignalR hub:
// JavaScript example
const connection = new signalR.HubConnectionBuilder()
.withUrl("/racehub?instance=your-slug")
.build();
// Request the current state
await connection.start();
await connection.invoke("RequestFullState");
// Listen for events
connection.on("ReceiveFullState", (state) => {
console.log("Full state:", state);
});
connection.on("ReceiveRaceEvent", (event) => {
console.log("Event:", event);
});
connection.on("ReceiveBatchEvents", (events) => {
console.log("Batch:", events);
});
Hub Methods
| Method | Direction | Description |
|---|---|---|
RequestFullState() | Client → Server | Request cached full state |
ReceiveFullState | Server → Client | Complete race snapshot |
ReceiveRaceEvent | Server → Client | Single race event |
ReceiveBatchEvents | Server → Client | Batch of race events |
Public Directory
The public live timing pages (those of /live, plus the collaborative sessions of the LapViz apps not marked private), for apps. Anonymous, 60 requests per minute per IP.
GET https://openlivetiming.com/api/directory?status=live&circuits=zolder,genk&limit=50
| Parameter | Description |
|---|---|
status | live (data in the last 10 minutes), upcoming (scheduled session in the next 60 days) or recent (data in the last 30 days), several separated by commas; all when omitted |
circuits | LapViz circuit codes separated by commas, case-insensitive (e.g. zolder); only the pages of these circuits |
limit | Maximum number of entries: 50 by default, 200 at most |
includeDemos | false to exclude the demo pages (isDemo: true); included by default |
Live pages come first (most recent activity first), then upcoming (soonest first), then recent; within each status, the real pages come before the demo pages. Track, session, flag and viewers are only given for the live pages.
{
"generatedAtUtc": "2026-10-19T12:00:00Z",
"entries": [ {
"slug": "spa-endurance", "title": "Spa 24h club race", "status": "live",
"circuitCode": "spakarting", "trackName": "Spa-Francorchamps", "sessionName": "Race 1",
"flag": "green", "viewerCount": 12, "lastActivityUtc": "2026-10-19T11:59:00Z", "startsAtUtc": null,
"url": "https://olt.live/lt/spa-endurance",
"eventName": "Club endurance", "accountName": "Karting Club", "isCollaborative": false, "isDemo": false
} ]
}
Add ?app=1 to a page shown in a native app's WebView: no site header, footer, push
notification or screen wake lock, links to other sites open in the same window.
OpenAPI Specification
The complete OpenAPI specification, with every request and response schema, is served at
/openapi/v1.json; in production it is restricted to the platform administrators. The sections above cover the endpoints
open to integrations.
Questions? Reach out at info@openlivetiming.com