Skip to content
TLGPSDocumentation

Developer documentation

Gateway / V1

Vehicle Topic

Gateway V1 connections, subscriptions and supported updates.

The vehicle topic provides Real-time telemetry for a single vehicle.

Clients subscribe using the vehicle UUID.

The vehicle UUID is identical to the UUID exposed by the REST API.

Only telemetry matching the subscribed resource is delivered to the client.

The Vehicle topic is currently the only supported subscription topic. Additional topics may be introduced in future protocol versions while preserving the existing message format.


Required Permission

Integration PAT connections require both the telemetry.subscribe PAT ability and effective telemetry.subscribe application permission. First-party browser-ticket connections require structural Tracking availability plus effective tracking.live_map and effective vehicles.view; they do not additionally require telemetry.subscribe because the one-use ticket was issued specifically for the first-party Tracking capability.

Vehicle permission and current Company/vehicle visibility constrain every subscription batch.


Subscription

{
    "type": "subscribe",
    "subscriptions": [
        {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    ]
}

Subscription Acknowledgement

If the subscription is accepted, the gateway responds with a subscribed message.

{
    "type": "subscribed",
    "timestamp": "2026-06-30T19:38:34+02:00",
    "data": {
        "subscription": {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    }
}

Receiving this message confirms that the subscription has been successfully registered and that Real-time events for the specified vehicle will begin streaming over the current Gateway connection.


Telemetry Event

Whenever new telemetry becomes available for the subscribed vehicle, the gateway sends a telemetry message.

{
    "type": "telemetry",
    "timestamp": "2026-06-30T19:53:37+02:00",
    "data": {
        "subscription": {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        },
        "vehicle": {
            "uuid": "01900000-0000-7000-8000-000000000001",
            "state": {
                "source": "realtime",
                "status": {
                    "connection": "online",
                    "movement": "parked"
                },
                "coordinates": {
                    "latitude": 0.0,
                    "longitude": 0.0
                },
                "geo_address": null,
                "speed": {
                    "kmh": 0,
                    "mps": 0
                },
                "gps_status": true,
                "angle": 61,
                "altitude": -1,
                "ignition": {
                    "status": "off"
                },
                "oil": 0,
                "voltage": 26.16,
                "mileage": {
                    "km": 27246189,
                    "meters": 27246189000
                },
                "temperature": "-255",
                "timestamps": {
                    "gps": "2026-06-30T17:52:51.000000Z",
                    "received": "2026-06-30T17:52:52.506493Z",
                    "last_synced": null
                }
            }
        }
    }
}

The vehicle.state object uses the same shared scalar projection as REST Vehicle Location for an equivalent resolved snapshot: coordinate numbers, speed/distance units and rounding, status values, booleans and optional nulls. No device UUID, raw provider payload or credentials are included.

Gateway V1 state timestamps.gps, received and last_synced are UTC ISO-8601 strings with six fractional digits and Z, or null. REST V1 retains its existing application-timezone offset format at second precision. These compatibility formats describe the same underlying measurements; parse timestamps and compare at the available precision rather than comparing strings. The Gateway envelope's top-level timestamp is the message send time, in application-timezone ISO-8601 at second precision; it is not the GPS measurement time.

geo_address uses the address already available on the snapshot, or null; serialization performs no reverse-geocoding request. Both transports expose display_name, city, state, country and country_code. Gateway V1 additionally retains the existing nullable geocoder reference fields place_id, osm_type and osm_id for backward compatibility. REST deliberately omits them. Initial state and later updates use this same Gateway representation; initial telemetry is still conditional on a snapshot being available.

The message envelope remains transport-specific. Separate reads and subscriptions may observe different snapshots, so no byte-identical REST/Gateway payload or delivery/latency guarantee is implied.


Unsubscribe Request

Clients may stop receiving telemetry by sending an unsubscribe message.

{
    "type": "unsubscribe",
    "subscriptions": [
        {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    ]
}

Unsubscription Acknowledgement

{
    "type": "unsubscribed",
    "timestamp": "2026-06-30T19:55:12+02:00",
    "data": {
        "subscription": {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    }
}

After receiving this message, no further telemetry events for the specified vehicle will be delivered unless the client subscribes again.


Vehicle Topic Notes

  • A client may subscribe to multiple vehicles simultaneously.
  • Vehicle subscriptions may be submitted together in one array request.
  • Vehicle UUIDs are identical to those used throughout the REST API.
  • Every telemetry message contains the subscription that generated the event.
  • The vehicle payload uses the same provider-independent tracking model as the REST API.
  • Telemetry is delivered only while the subscription remains active.
  • Applications should tolerate receiving duplicate telemetry events.

Events

A successful subscription receives telemetry messages whenever new telemetry becomes available for the subscribed vehicle.

The gateway delivers only telemetry belonging to the requested vehicle.

Multiple vehicle subscriptions may exist simultaneously on the same Gateway connection.

Public documentation · authorized integration access required

Engineering-maintained documentation. Examples use synthetic data and placeholder credentials.

Back to top