Public viewer feedWebSocket · Protocol v1

Subscribe once. Render every snapshot.

Connect and subscribe to a live company and game telemetry feed.

Gateway connectionOPEN
Secure WebSocketwss://gateway.tracksim.app/v1/ws
CLIENTsubscribe
{
  "version": 1,
  "op": "subscribe",
  "data": { "company_id": 42, "game": "eut2" }
}
GATEWAY EVENTTELEMETRY_SNAPSHOT
1,000 ms
AccessPublic viewerNo account or API key
TransportSecure WebSocketUTF-8 JSON text frames
UpdatesFull snapshotsConfigured feed interval
ProtocolVersion 1256 KiB message limit

#Connect to the Gateway

Public viewers connect to the following secure WebSocket endpoint:

text
wss://gateway.tracksim.app/v1/ws

No 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:

json
{
  "version": 1,
  "op": "subscribe",
  "data": {
    "company_id": 42,
    "game": "eut2"
  }
}
PropertyTypeDescription
versionintegerProtocol version. Use 1.
opstringOperation name. Use subscribe for a public viewer.
data.company_idintegerCompany whose live feed you want to view.
data.gamestringGame 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:

json
{
  "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:

json
{
  "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
        }
      }
    ]
  }
}
PropertyTypeDescription
versionintegerProtocol version.
opstringevent for server events.
typestringTELEMETRY_SNAPSHOT for a full feed snapshot.
data.company_idintegerCompany represented by this snapshot.
data.gamestringGame represented by this snapshot.
data.generated_at_msintegerSnapshot generation time in Unix milliseconds.
data.driversarrayFull 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

PropertyTypeDescription
driverstringDriver Steam ID.
usernamestringDriver display name.
vehicle_typestring or nullCurrent vehicle category, for example truck or car.
jobobject or nullCurrent delivery details. null when the driver has no active job.
multiplayerobjectMultiplayer mode and its metadata. Values can be empty outside a supported multiplayer session.
promodsbooleanWhether ProMods is active for the driver.
routearrayRecent timestamped game-world positions. The list can be empty.
trailersarrayCurrent trailer objects. The list can be empty.
truckobjectCurrent vehicle telemetry.

#Job object

PropertyTypeDescription
cargo.namestringCargo display name.
source.city.namestringOrigin city.
source.company.namestringOrigin company.
destination.city.namestringDestination city.
destination.company.namestringDestination company.

#Multiplayer object

PropertyTypeDescription
modestringMultiplayer integration, for example truckersmp or haulmp. Can be an empty string.
meta.player_idstringPlayer identifier reported by the multiplayer integration. Can be empty.
meta.serverstringConnected server name. Can be empty.

#Route point

PropertyTypeDescription
timeintegerRoute sample timestamp in Unix seconds.
xnumberGame-world X coordinate.
znumberGame-world Z coordinate.

#Truck object

PropertyTypeDescription
brand.namestringVehicle manufacturer.
namestringVehicle model name.
current_damageobjectCurrent cabin, chassis, engine, transmission, and wheels damage values.
fuel.amountnumberCurrent fuel amount reported by telemetry.
hookobjectHook x, y, and z coordinates.
positionobjectCurrent game-world x and z coordinates.
speednumberCurrent speed reported by telemetry.

#Trailer object

PropertyTypeDescription
attachedbooleanWhether the trailer is attached.
bodystringTrailer body type.
current_damage.chassisnumberCurrent trailer chassis damage.
hookobjectTrailer hook x, y, and z coordinates.
positionobjectTrailer game-world x and z coordinates.
rotation.headingnumberTrailer 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

javascript
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_SKIPS consecutive 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.