TripQube Developer APIs

Multiple integration options for different use cases. Build companion apps with Bluetooth, track locations with REST APIs, or integrate hardware devices via MQTT.

📡 Bluetooth Low Energy Integration

Build companion apps that receive real-time navigation data from TripQube over Bluetooth Low Energy. Perfect for HUD glasses, smartwatch displays, custom dashboards, and IoT devices.

What You Can Receive

• ✅ Real-time navigation: Maneuver instructions, distance, arrival time
• ✅ Current position: GPS coordinates, bearing, speed (1 Hz updates)
• ✅ Route geometry: Complete route path for visual displays
• ✅ Waypoints: Multi-stop routes with check-in status
• ✅ Road context: Major and minor roads near your position
• ✅ Travel history: Path already ridden during the current trip

Quick Start: Connect and Listen

// Scan for TripQube Bluetooth service
val scanner = bluetoothAdapter?.bluetoothLeScanner ?: return
val filter = ScanFilter.Builder()
    .setServiceUuid(ParcelUuid(SERVICE_UUID))
    .build()
scanner.startScan(listOf(filter), scanSettings(), scanCallback)

// Listen for navigation data
gatt.setCharacteristicNotification(navCharacteristic, true)

override fun onCharacteristicChanged(
    gatt: BluetoothGatt,
    characteristic: BluetoothGattCharacteristic,
    value: ByteArray
) {
    val frame = decode(value)  // Parse the binary frame
    when (frame) {
        is NavUpdate -> updateNavigation(frame)
        is Position -> updatePosition(frame)
        // Handle other frame types...
    }
}

Frame Types

Maneuver Codes Reference

Parse Navigation Frame

data class NavUpdate(
    val maneuverCode: Int,
    val distanceMetres: Int,
    val arrivalMinutes: Int?,
    val instruction: String,
    val altitudeMetres: Int?
)

// Frame format (9+ bytes):
// Offset  Size  Field
// 0       1     Version (6)
// 1       1     Type (1 = NAV)
// 2       1     Maneuver code
// 3..4    2     Distance metres (uint16)
// 5..6    2     Arrival minutes (0xFFFF = unknown)
// 7..8    2     Altitude metres (0x7FFF = unknown)
// 9+      var   Instruction text (UTF-8)

Parse Position Frame

data class Position(
    val latitude: Double,
    val longitude: Double,
    val bearingDegrees: Float?,
    val speedKph: Int
)

// Frame format (14 bytes):
// Offset  Size  Field
// 0       1     Version (6)
// 1       1     Type (2 = POSITION)
// 2..5    4     Latitude (degrees × 10^7, int32)
// 6..9    4     Longitude
// 10..11  2     Bearing tenths of degree (0xFFFF = unknown)
// 12      1     Speed km/h (uint8)

Permissions Required

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />

Performance Tips

• MTU negotiation: Request higher MTU (up to 517 bytes) to receive more data per packet: gatt.requestMtu(517)
• Scan mode: Use SCAN_MODE_LOW_POWER to reduce battery drain
• Coalesce updates: Queue frames instead of rendering each one if your UI is slow
• Route changes: Only redraw routes when generation ID changes (indicates new route)
• Reconnection: Implement exponential backoff for reconnect attempts

🔌 REST API (HTTP) Integration

Integrate GPS tracking and location services using our HTTP REST API. Perfect for web applications, server-side integrations, and general-purpose development.

📝 Register Approved Device

Register a new hardware device to the TripQube system. This is a public endpoint that does not require user authentication.

Request Body

{
  "device_id": "TRK-ABC-12345",
  "pin": "98765",
  "firmware_version": "2.1.0",
  "manufacturer": "TripQube Hardware"
}

Request Parameters

Success Response (200 OK)

{
  "success": true,
  "message": "Approved device registered successfully.",
  "device_id": "TRK-ABC-12345"
}

📍 Push Tracker Location

Push location data from your hardware device to update tracker position. Supports both single location updates and buffered batch updates for offline scenarios.

Single Location Update

{
  "device_id": "TRK-ABC-12345",
  "pin": "98765",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "battery_level": 85,
  "timestamp": 1705012345000
}

Buffered Locations (Batch Update)

{
  "device_id": "TRK-ABC-12345",
  "pin": "98765",
  "location_buffer": [
    {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "timestamp": 1705012345000,
      "speed": 15.5,
      "altitude": 50
    },
    {
      "latitude": 37.7750,
      "longitude": -122.4195,
      "timestamp": 1705012375000,
      "speed": 20.2,
      "altitude": 55
    }
  ],
  "battery_level": 84
}

Request Parameters

* Either (latitude AND longitude) OR location_buffer must be provided.

💻 Integration Examples

Python

Simple Python implementation for pushing location data via HTTP.

import requests
import time

DEVICE_ID = "TRK-ABC-12345"
PIN = "98765"
PUSH_URL = "https://pushtrackerlocation-3y3utatgia-uc.a.run.app"

def push_location(lat, lon, battery=None):
    payload = {
        "device_id": DEVICE_ID,
        "pin": PIN,
        "latitude": lat,
        "longitude": lon,
        "timestamp": int(time.time() * 1000)
    }
    
    if battery is not None:
        payload["battery_level"] = battery
    
    response = requests.post(PUSH_URL, json=payload)
    return response.json()

# Usage
result = push_location(37.7749, -122.4194, battery=85)
print(result)

JavaScript/Node.js

Example implementation for Node.js server applications.

const axios = require('axios');

const DEVICE_ID = 'TRK-ABC-12345';
const PIN = '98765';
const PUSH_URL = 'https://pushtrackerlocation-3y3utatgia-uc.a.run.app';

async function pushLocation(lat, lon, battery = null) {
  const payload = {
    device_id: DEVICE_ID,
    pin: PIN,
    latitude: lat,
    longitude: lon,
    timestamp: Date.now()
  };

  if (battery !== null) {
    payload.battery_level = battery;
  }

  const response = await axios.post(PUSH_URL, payload);
  return response.data;
}

// Usage
pushLocation(37.7749, -122.4194, 85)
  .then(result => console.log(result));

💬 Support & Resources