Telemetry API

Endpoints

Method	Path	Description
GET	/api/devices/:id/telemetry	Query telemetry history
GET	/api/devices/:id/location	Current device location
GET	/api/devices/:id/track	GPS track for map playback
GET	/api/devices/:id/events	Device events
GET	/api/devices/:id/trips	Trip history

Query Telemetry

GET /api/devices/:id/telemetry?from=2026-05-24T00:00:00Z&to=2026-05-24T12:00:00Z&limit=1000

Query Parameters

Parameter	Type	Required	Description
from	ISO 8601	Yes	Start of time range
to	ISO 8601	Yes	End of time range
limit	int	No	Max records (default 1000, max 10000)
metrics	string	No	Comma-separated metric filter

Response (200)

{
  "deviceId": "uuid",
  "data": [
    {
      "timestamp": "2026-05-24T10:30:00Z",
      "system": {
        "cpuLoad": 0.12,
        "memoryUsed": 42,
        "uptime": 432000
      },
      "cellular": {
        "rsrp": -82,
        "rsrq": -8,
        "sinr": 15,
        "band": "B3",
        "technology": "LTE"
      },
      "network": {
        "wanType": "cellular",
        "failoverActive": false
      },
      "gps": {
        "lat": 40.7128,
        "lon": -74.0060,
        "speed": 45.5,
        "heading": 180,
        "altitude": 10,
        "satellites": 12,
        "hdop": 0.8
      }
    }
  ],
  "count": 720,
  "timeRange": {
    "from": "2026-05-24T00:00:00Z",
    "to": "2026-05-24T12:00:00Z"
  }
}

Current Location

GET /api/devices/:id/location

Returns the most recent GPS position from the device state cache.

Response (200)

{
  "deviceId": "uuid",
  "location": {
    "lat": 40.7128,
    "lon": -74.0060,
    "speed": 0,
    "heading": 180,
    "altitude": 10,
    "satellites": 12,
    "hdop": 0.8,
    "fix": "3D"
  },
  "timestamp": "2026-05-24T10:30:00Z",
  "age": 45
}

Field	Description
age	Seconds since this position was reported

GPS Track

GET /api/devices/:id/track?from=2026-05-24T08:00:00Z&to=2026-05-24T12:00:00Z

Returns GPS points optimized for map polyline rendering.

Response (200)

{
  "deviceId": "uuid",
  "track": [
    {
      "lat": 40.7128,
      "lon": -74.0060,
      "speed": 45.5,
      "heading": 180,
      "timestamp": "2026-05-24T08:00:00Z"
    },
    {
      "lat": 40.7135,
      "lon": -74.0055,
      "speed": 52.0,
      "heading": 175,
      "timestamp": "2026-05-24T08:00:30Z"
    }
  ],
  "pointCount": 480,
  "distance": 28.5,
  "duration": 14400
}

Field	Description
pointCount	Number of GPS points in track
distance	Total distance in km
duration	Total time in seconds

Device Events

GET /api/devices/:id/events?from=2026-05-24T00:00:00Z&type=ignition

Query Parameters

Parameter	Type	Description
from	ISO 8601	Start time
to	ISO 8601	End time
type	string	Filter by event type
severity	string	Filter: info, warning, critical
limit	int	Max results

Event Types

Type	Description
ignition_on	Vehicle ignition turned on
ignition_off	Vehicle ignition turned off
trip_start	Trip started
trip_end	Trip ended
speeding	Speed exceeded threshold
geofence_enter	Entered geofenced area
geofence_exit	Left geofenced area
device_online	Device came online
device_offline	Device went offline
failover	WAN failover triggered

Response (200)

{
  "data": [
    {
      "id": "event-id",
      "timestamp": "2026-05-24T08:15:00Z",
      "eventType": "ignition_on",
      "severity": "info",
      "metadata": {
        "lat": 40.7128,
        "lon": -74.0060
      }
    }
  ],
  "count": 24
}

Trip History

GET /api/devices/:id/trips?from=2026-05-01T00:00:00Z&to=2026-05-24T23:59:59Z

Response (200)

{
  "data": [
    {
      "id": "trip-uuid",
      "status": "completed",
      "startTime": "2026-05-24T08:15:00Z",
      "endTime": "2026-05-24T09:30:00Z",
      "startLocation": {"lat": 40.7128, "lon": -74.0060},
      "endLocation": {"lat": 40.7589, "lon": -73.9851},
      "distance": 12.3,
      "maxSpeed": 65.0,
      "avgSpeed": 28.5,
      "idleSeconds": 420,
      "pointCount": 150
    }
  ],
  "count": 3
}

Data Export

For bulk data export:

GET /api/devices/:id/telemetry/export?from=2026-05-01&to=2026-05-24&format=csv

Supported formats: json, csv

Returns a download link for large datasets (processed async for > 10,000 records).