Subscribe once. Render every snapshot.
Connect and subscribe to a live company and game telemetry feed.
wss://gateway.tracksim.app/v1/ws#Connect to the Gateway
Public viewers connect to the following secure WebSocket endpoint:
wss://gateway.tracksim.app/v1/wsNo account or API key is required. This guide covers subscribing to and receiving a public feed.
Clients send UTF-8 JSON text frames. Binary frames are not part of protocol version 1. Incoming messages are limited to 256 KiB by default.
#Subscribe to a feed
The first valid message must establish the connection as a public viewer before the server's configured WS_ROLE_TIMEOUT_MS expires. Send a subscribe operation with the company and game feed you want to view:
{
"version": 1,
"op": "subscribe",
"data": {
"company_id": 42,
"game": "eut2"
}
}| Property | Type | Description |
|---|---|---|
version | integer | Protocol version. Use 1. |
op | string | Operation name. Use subscribe for a public viewer. |
data.company_id | integer | Company whose live feed you want to view. |
data.game | string | Game feed to view, for example eut2. |
Once this message is accepted, the connection is subscribed as a public viewer. Unsupported operations produce an ERROR event.
#Subscription confirmation
The Gateway confirms the active feed with a SUBSCRIBED event:
{
"version": 1,
"op": "event",
"type": "SUBSCRIBED",
"data": {
"company_id": 42,
"game": "eut2",
"snapshot_interval_ms": 1000
}
}The snapshot_interval_ms value tells you how often the Gateway is configured to send snapshots for this subscription.
#Receive telemetry snapshots
After confirmation, the Gateway sends full TELEMETRY_SNAPSHOT events at the configured interval:
{
"version": 1,
"op": "event",
"type": "TELEMETRY_SNAPSHOT",
"data": {
"company_id": 42,
"game": "eut2",
"generated_at_ms": 1794570360604,
"drivers": [
{
"driver": "76561198000000000",
"username": "Example Driver",
"vehicle_type": "truck",
"job": {
"cargo": {
"name": "Ketchup"
},
"source": {
"city": {
"name": "Parma"
},
"company": {
"name": "Tesoro Gustoso"
}
},
"destination": {
"city": {
"name": "Jyväskylä"
},
"company": {
"name": "Vitas Power"
}
}
},
"multiplayer": {
"mode": "truckersmp",
"meta": {
"player_id": "625",
"server": "Server 4"
}
},
"promods": false,
"route": [
{
"time": 1794570056,
"x": 28405.616455078125,
"z": -15799.825675964355
},
{
"time": 1794570061,
"x": 28472.11004638672,
"z": -15846.144718170166
}
],
"trailers": [
{
"attached": true,
"body": "curtainside",
"current_damage": {
"chassis": 0.027918556705117226
},
"hook": {
"x": 0,
"y": 1,
"z": -4.968114376068115
},
"position": {
"x": 29667.296087265015,
"z": -19123.01481628418
},
"rotation": {
"heading": 0.7329810857772827
}
}
],
"truck": {
"brand": {
"name": "DAF"
},
"current_damage": {
"cabin": 0.009309615008533001,
"chassis": 0.011637018993496895,
"engine": 0.011725571006536484,
"transmission": 0.010460477322340012,
"wheels": 0.17786727845668793
},
"fuel": {
"amount": 367.2578125
},
"hook": {
"x": 0,
"y": 0.999744176864624,
"z": 1.6522263288497925
},
"name": "NGD",
"position": {
"x": 29673.877025604248,
"z": -19122.310256958008
},
"speed": 24.90380605061849
}
}
]
}
}| Property | Type | Description |
|---|---|---|
version | integer | Protocol version. |
op | string | event for server events. |
type | string | TELEMETRY_SNAPSHOT for a full feed snapshot. |
data.company_id | integer | Company represented by this snapshot. |
data.game | string | Game represented by this snapshot. |
data.generated_at_ms | integer | Snapshot generation time in Unix milliseconds. |
data.drivers | array | Full list of drivers currently included in the feed. The list can be empty. |
Treat each event as a complete snapshot of the active feed rather than a partial update.
#Driver object
| Property | Type | Description |
|---|---|---|
driver | string | Driver Steam ID. |
username | string | Driver display name. |
vehicle_type | string or null | Current vehicle category, for example truck or car. |
job | object or null | Current delivery details. null when the driver has no active job. |
multiplayer | object | Multiplayer mode and its metadata. Values can be empty outside a supported multiplayer session. |
promods | boolean | Whether ProMods is active for the driver. |
route | array | Recent timestamped game-world positions. The list can be empty. |
trailers | array | Current trailer objects. The list can be empty. |
truck | object | Current vehicle telemetry. |
#Job object
| Property | Type | Description |
|---|---|---|
cargo.name | string | Cargo display name. |
source.city.name | string | Origin city. |
source.company.name | string | Origin company. |
destination.city.name | string | Destination city. |
destination.company.name | string | Destination company. |
#Multiplayer object
| Property | Type | Description |
|---|---|---|
mode | string | Multiplayer integration, for example truckersmp or haulmp. Can be an empty string. |
meta.player_id | string | Player identifier reported by the multiplayer integration. Can be empty. |
meta.server | string | Connected server name. Can be empty. |
#Route point
| Property | Type | Description |
|---|---|---|
time | integer | Route sample timestamp in Unix seconds. |
x | number | Game-world X coordinate. |
z | number | Game-world Z coordinate. |
#Truck object
| Property | Type | Description |
|---|---|---|
brand.name | string | Vehicle manufacturer. |
name | string | Vehicle model name. |
current_damage | object | Current cabin, chassis, engine, transmission, and wheels damage values. |
fuel.amount | number | Current fuel amount reported by telemetry. |
hook | object | Hook x, y, and z coordinates. |
position | object | Current game-world x and z coordinates. |
speed | number | Current speed reported by telemetry. |
#Trailer object
| Property | Type | Description |
|---|---|---|
attached | boolean | Whether the trailer is attached. |
body | string | Trailer body type. |
current_damage.chassis | number | Current trailer chassis damage. |
hook | object | Trailer hook x, y, and z coordinates. |
position | object | Trailer game-world x and z coordinates. |
rotation.heading | number | Trailer heading. |
#Change feeds
A public viewer may switch feeds without reconnecting. Send another subscribe operation with the new company_id and game. Wait for the next SUBSCRIBED event before treating the new feed as active.
#Browser example
const socket = new WebSocket("wss://gateway.tracksim.app/v1/ws");
socket.addEventListener("open", () => {
socket.send(JSON.stringify({
version: 1,
op: "subscribe",
data: {
company_id: 42,
game: "eut2",
},
}));
});
socket.addEventListener("message", ({ data }) => {
const message = JSON.parse(data);
if (message.op !== "event") return;
if (message.type === "SUBSCRIBED") {
console.log("Active Gateway feed", message.data);
}
if (message.type === "TELEMETRY_SNAPSHOT") {
console.log("Telemetry snapshot", message.data);
}
if (message.type === "ERROR") {
console.error("Gateway error", message);
}
});#Errors and connection closure
An operation that is invalid for a public viewer produces an ERROR event. A fatal error is followed by the Gateway closing the WebSocket connection.
When reconnecting after a closure, open a new WebSocket and send the subscription again within WS_ROLE_TIMEOUT_MS. Do not assume that the previous feed remains active.
#Slow-viewer protection
The Gateway applies backpressure so a slow viewer does not accumulate an unbounded queue of snapshots:
- A snapshot is skipped while the socket buffer exceeds
SLOW_CLIENT_MAX_BUFFER_BYTES. - After
SLOW_CLIENT_MAX_SKIPSconsecutive skips, the Gateway closes the connection as retryable.
If this happens repeatedly, make snapshot processing faster and avoid blocking the WebSocket message handler before reconnecting.