Integrating GPS Data Transmission to Telemetry

1. Overview

DeliTMS receives GPS through a separate service — Telemetry — optimized for time-series write/read operations. Any source (vehicle-mounted tracker device, company mobile app, third-party GPS gateway) can push location data via a single HTTP API. DeliTMS automatically attaches GPS points to the correct vehicle/trip, displays them on the Map and Monitoring pages (see chapter 12), and runs alert analysis with real-time monitoring capabilities.

If your company uses the DeliTMS driver app, the app already sends GPS automatically — no additional integration needed. This guide is for when you use your own GPS device/system.

2. Obtaining Keys & Authentication

Each sender is issued an API key in the format dtms_… (contact the DeliTMS deployment team to obtain a key for your company). Attach the key to every request via header:

X-Api-Key: dtms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Or use Authorization: Bearer dtms_…. Missing/incorrect key → 401. Keep the key secret — only place it on the device/server side, do not embed it in end-user applications. IMEI authentication is also supported for hardware trackers.

3. GPS Transmission Endpoint

POST {TELEMETRY_URL}/gps/ingest
Content-Type: application/json
X-Api-Key: dtms_…

{TELEMETRY_URL} is the Telemetry service address provided by DeliTMS (e.g., https://telemetry.delitms.com). Each request sends one GPS point for one vehicle, enabling efficient GPS data transmission.

4. Two Ways to Identify Vehicles

Telemetry needs to know which vehicle the GPS point belongs to. Choose one of two methods:

For hardware trackers, use IMEI mode: when the company changes/reassigns vehicles to devices, just update the device assignment in DeliTMS—the GPS sender doesn't need to change anything.

5. Request Body (JSON)

{
  "imei": "SN-0864221135",        // or: "vehicle_id": 558
  "company_id": 22,
  "source": "tracker",             // "tracker" (device) | "app" (application)
  "latitude": 10.776900,
  "longitude": 106.696600,
  "speed": 45.5,                   // km/h
  "heading": 180,                  // degrees, 0–360
  "accuracy": 8.0,                 // meters
  "status": "moving",              // moving | stopped | idle
  "timestamp": 1714298401,         // Unix seconds; omit = time of receipt
  "metadata": { "driver_id": 123, "trip_id": "ABC-001", "fuel_level_pct": 78.4 }
}

* Must have one of two: imei OR (vehicle_id + company_id). When using imei, should still include company_id.

Response. Success: 200 { "success": true, "latency_ms": 42 }. Missing field: 400 { "error": "field 'vehicle_id' is required" }. Write error: 500. Incorrect/missing key: 401.

6. Examples

6.1. curl

curl -X POST "$TELEMETRY_URL/gps/ingest" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $TELEMETRY_API_KEY" \
  -d '{
    "imei": "SN-0864221135", "company_id": 22, "source": "tracker",
    "latitude": 10.7769, "longitude": 106.6966,
    "speed": 45.5, "heading": 180, "status": "moving",
    "timestamp": '"$(date +%s)"'
  }'

6.2. Node.js

async function sendGps({ imei, companyId, lat, lng, speed, heading, status }) {
  const res = await fetch(`${process.env.TELEMETRY_URL}/gps/ingest`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': process.env.TELEMETRY_API_KEY,
    },
    body: JSON.stringify({
      imei, company_id: companyId, source: 'tracker',
      latitude: Number(lat.toFixed(6)), longitude: Number(lng.toFixed(6)),
      speed: Number(speed.toFixed(1)), heading: Number(heading.toFixed(1)),
      status, timestamp: Math.floor(Date.now() / 1000),
    }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  return res.json();
}

// Send periodically (e.g., every 10–15 seconds) when vehicle is running:
setInterval(async () => {
  const p = readGpsFromDevice();            // lat/lng/speed/heading from device
  try { await sendGps({ imei: 'SN-0864221135', companyId: 22, ...p, status: p.speed > 0 ? 'moving' : 'idle' }); }
  catch (e) { console.warn('gps send error (will retry next time):', e.message); }
}, 10000);

6.3. Hardware Tracker Device

If the tracker can only send raw HTTP: configure it to POST to {TELEMETRY_URL}/gps/ingest, add X-Api-Key header, body JSON as above with imei = device serial. DeliTMS automatically maps serial → vehicle via device assignment record (30-second cache), enabling seamless vehicle tracking and API integration.

7. Frequency & Best Practices

• Frequency: 5–15 seconds/point when vehicle is moving is reasonable (smooth enough for map + alerts, saves battery/bandwidth). When stopped, can be less frequent.
• Retry on error: if request fails due to network error, retry at next interval — no need to block the flow. Old point still uses original timestamp.
• Set status correctly for accurate alerts/history: moving when speed > 0, idle when stationary with engine on, stopped when engine off.
• Sync device time (NTP) so timestamp doesn't drift.

8. Reading Sent Data

Besides sending, Telemetry also allows reading (same X-Api-Key): GET /gps/history (history by vehicle/time range), GET /gps/events (alert events: speeding, route deviation…), GET /gps/summary/daily (daily KPIs). Sent data also appears immediately on the portal's Map & Monitoring pages.