Tracking API

Overview

The Tracking API enables real-time location streaming between drivers (or mobile agents) and offices (or control centers) using secure WebSocket connections.

This API is designed for fleet tracking, delivery monitoring, dispatch systems, and live map visualization, allowing multiple roles to communicate through a single persistent connection.

With support for authentication, subscriptions, and continuous location updates, the Tracking API ensures low-latency, scalable, and reliable tracking across your organization.

Key Features

• 🚗 Real-time driver location updates

• 🏢 Office subscriptions to specific drivers or all drivers

• 📡 Low-latency WebSocket streaming

Connection Endpoint

wss://track.gebeta.app/v1/track

Roles

Use Cases

Authentication Flow

All clients must authenticate immediately after connection.

Authenticate Message

{
  "action": "authenticate",
  "payload": {
    "user_id": "DR_1",
    "role": "driver",
    "token": "<JWT_TOKEN>"
  }
}

Parameters

Driver: Sending Location Updates

Once authenticated, a driver can continuously send location updates.

Location Update Message

{
  "action": "driver_location",
  "id": "DR_1",
  "payload": {
    "lat": 9.01234,
    "lng": 38.70321,
    "speed": 14.5,
    "bearing": 90
  }
}

Payload Fields

📌 Recommended update interval: 2–5 seconds

Office: Subscribing to Drivers

Offices can subscribe to specific drivers or all drivers.

Subscribe to a Specific Driver

{
  "action": "subscribe",
  "entity": "driver:DR_1"
}

Subscribe to All Drivers in the Company

{
  "action": "subscribe",
  "entity": "company:drivers"
}

Receiving Location Updates (Office)

Subscribed offices receive real-time updates in the following format:

{
  "type": "location_update",
  "id": "DR_1",
  "payload": {
    "lat": 9.01345,
    "lng": 38.70412,
    "speed": 13.2,
    "bearing": 90
  }
}

Heartbeat (Ping / Pong)

The server may send WebSocket ping frames to ensure connection health.

Clients must respond with pong:

ws.on("ping", () => {
  ws.pong();
});

Example Implementations

const WebSocket = require("ws");
const ws = new WebSocket("wss://track.gebeta.app/v1/track");
 
ws.on("open", () => {
  ws.send(JSON.stringify({
    action: "authenticate",
    payload: {
      user_id: "DR_1",
      role: "driver",
      token: "<JWT_TOKEN>"
    }
  }));
 
  setInterval(() => {
    ws.send(JSON.stringify({
      action: "driver_location",
      id: "DR_1",
      payload: {
        lat: 9.01 + Math.random() * 0.01,
        lng: 38.70 + Math.random() * 0.01,
        speed: 12,
        bearing: 90
      }
    }));
  }, 3000);
});

Error Handling

Limits & Restrictions

• 🔄 Max connections: Configurable per company

• 📡 Location update rate: Max 1 update per second per driver

• 🔐 Token expiration: Connections close automatically on expiry

• 🏢 Company isolation: Offices only receive data from their company