Skip to main content
POST
/
v1
/
trips
/
{sessionId}
/
gps
/
batch
Upload GPS Batch
curl --request POST \
  --url https://api.bookovia.com/v1/trips/{sessionId}/gps/batch \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "driver_id": "<string>",
  "vehicle_id": "<string>",
  "points": [
    {
      "latitude": 123,
      "longitude": 123,
      "speed": 123,
      "accuracy": 123,
      "recorded_at": "<string>",
      "altitude": 123,
      "heading": 123,
      "acceleration_x": 123,
      "acceleration_y": 123,
      "acceleration_z": 123,
      "g_force_magnitude": 123,
      "rotation_x": 123,
      "rotation_y": 123,
      "rotation_z": 123,
      "magnetic_x": 123,
      "magnetic_y": 123,
      "magnetic_z": 123,
      "magnetic_bearing": 123,
      "pressure": 123,
      "pressure_altitude": 123,
      "satellite_count": 123,
      "hdop": 123,
      "vdop": 123,
      "location_provider": "<string>",
      "is_mocked": true,
      "activity": "<string>",
      "activity_confidence": 123,
      "battery_level": 123,
      "battery_temp": 123,
      "is_charging": true,
      "is_screen_on": true,
      "app_in_foreground": true,
      "light_level": 123,
      "noise_level": 123,
      "is_call_active": true,
      "touch_count": 123,
      "network_type": "<string>",
      "wifi_ssid": "<string>",
      "wifi_strength": 123,
      "bluetooth_devices": [
        {}
      ],
      "step_count": 123,
      "engine_rpm": 123,
      "throttle_pos": 123,
      "engine_load": 123,
      "fuel_level": 123,
      "coolant_temp": 123
    }
  ]
}
'
{
  "success": true,
  "trip_id": "<string>",
  "points_saved": 123,
  "storage": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.bookovia.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Upload GPS Batch endpoint accepts batches of GPS location points from mobile devices for an active trip. This endpoint is optimized for offline-first architectures where devices buffer GPS data locally and sync when connectivity is available.
This endpoint performs a triple-write to three storage tiers:
  • Redis Stream (HOT - 15min TTL) for real-time crash detection
  • DuckDB (WARM - 48 hours) for fast mileage queries
  • Parquet PVC (COLD - 90 days) for archival and S3 upload

​
Authentication

This endpoint requires authentication via API key in the X-API-Key header. Required permissions: trips:write, telemetry:write

​
Path Parameters

​
sessionId
string
required
The trip ID returned from the Start Trip endpoint

​
Request

​
driver_id
string
Driver identifier (optional, extracted from trip if not provided)
​
vehicle_id
string
Vehicle identifier (optional, extracted from trip if not provided)
​
points
array
required
Array of GPS location points with enterprise sensor data (maximum 100 points per request)

​
Request Example

curl -X POST https://api.bookovia.com/v1/trips/trip-abc-123/gps/batch \
  -H "X-API-Key: bkv_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {
        "latitude": 40.7128,
        "longitude": -74.0060,
        "speed": 12.5,
        "accuracy": 5.0,
        "g_force_magnitude": 1.02,
        "battery_level": 85,
        "network_type": "5G",
        "recorded_at": "2026-04-29T12:00:00.000Z"
      }
    ]
  }'

​
Response

​
success
boolean
Whether the upload was successful
​
trip_id
string
The trip ID that received the GPS points
​
points_saved
integer
Number of points successfully saved
​
storage
string
Storage destinations where data was written (e.g., “duckdb_parquet”)

​
Success Response

{
  "success": true,
  "trip_id": "trip-abc-123",
  "points_saved": 100,
  "storage": "duckdb_parquet"
}

​
Error Responses

​
404 Not Found

{
  "success": false,
  "error": "Trip not found"
}

​
400 Bad Request

{
  "success": false,
  "error": "Cannot upload GPS to trip with status: completed"
}

​
Backend Architecture

This endpoint performs a triple-write to ensure data durability and real-time capabilities:

​
1. Redis Stream (HOT Tier)

  • Purpose: Real-time crash detection and alerts
  • TTL: 15 minutes
  • Storage: In-memory
  • Key: gps:stream:{org_id}
  • Use Case: Crash detection worker reads stream, checks G-force > 3.0g

​
2. DuckDB .duckdb (WARM Tier)

  • Purpose: Fast mileage queries for recent trips
  • Retention: 48 hours
  • Storage: Northflank PVC at /data/telemetry/telemetry.duckdb
  • Query Speed: 10-30ms
  • Use Case: Real-time mileage calculation, live dashboard

​
3. Parquet PVC (COLD Tier)

  • Purpose: Archival for S3 upload
  • Retention: 90 days
  • Storage: Northflank PVC at /data/telemetry/location_points/year=YYYY/month=MM/day=DD/
  • Compression: Snappy (~10:1 ratio)
  • Use Case: Weekly S3 upload, historical analysis

​
Enhanced Crash Detection (Multi-Sensor Fusion)

The backend uses multi-sensor fusion for 99% accurate crash detection. A crash is detected when: 
Crash Score = (
  g_force > 3.0 (50% weight) +
  rotation magnitude > 3.0 rad/s (20% weight) +
  noise_level > 100 dB (20% weight) +
  speed > 10 m/s before event (10% weight)
)

Crash Detected if Score ≥ 60%

​
Crash Response Flow:

  1. Immediate Detection (less than 100ms)
    • Redis Stream processes GPS point in real-time
    • Multi-sensor algorithm calculates crash score
    • If score ≥ 60%, trigger crash event
  2. Automatic Actions
    • Save to crash_events table with sensor data
    • Push notification: “Are you OK? Tap if safe”
    • 60-second countdown timer starts
  3. If No Response
    • Alert emergency contacts
    • Notify fleet manager
    • Send GPS coordinates
    • (Optional) Call emergency services
  4. Data Logged
    • All sensor readings 10 seconds before crash
    • G-force magnitude, rotation, noise level
    • Speed, location, altitude
    • Photos from dash cam (if available)

​
Enterprise Analytics Enabled

With 60+ sensor fields, the following analytics are automatically calculated:

​
Safety & Risk

  • Distracted Driving Score: screen_on + touches + rotation_variance + calls
  • Harsh Events: Braking/acceleration greater than 3 m/s²
  • Speeding Detection: Compare actual speed vs posted limits
  • Night Driving Hours: light_level < 10 lux = 3x crash risk
  • Phone Usage While Driving: Call active + movement

​
Driver Performance

  • Driver Ranking: Multi-dimensional scoring
  • Eco-Driving Score: Smooth acceleration, optimal speed
  • Idle Time Detection: speed < 0.5 m/s for more than 2 minutes
  • Route Efficiency: Actual vs optimal path

​
Vehicle Health

  • Predictive Maintenance: High RPM + harsh events = wear
  • Engine Health Score: DTC codes from OBD-II
  • Fuel Efficiency: Real consumption vs driving style
  • Battery Health: Temperature patterns

​
Environmental Impact

  • CO2 Emissions: Estimated from fuel + driving pattern
  • Fuel Consumption: L/100km calculation
  • ESG Reporting: Corporate sustainability metrics

​
Fraud Detection

  • Mock GPS Detection: is_mocked = true flag
  • GPS Quality Score: Satellite count + HDOP
  • Activity Mismatch: Activity ≠ “driving” but speed greater than 20 km/h

​
Auto Trip Detection

  • Smart Start: Bluetooth car connected + activity = “driving”
  • Smart Stop: Activity = “walking” + step count increasing
  • Driver vs Passenger: Gyroscope patterns + activity

​
Rate Limits

  • Standard: 60 requests per minute (6,000 points/minute)
  • Professional: 300 requests per minute (30,000 points/minute)
  • Enterprise: 1,000 requests per minute (100,000 points/minute)

​
Best Practices

​
Batch Size

  • Upload 100 points per request (maximum)
  • Mobile app should batch locally and sync every 60 seconds when online

​
Offline Mode

  • Buffer GPS points in SQLite when no internet connection
  • Mark points with synced=0 flag
  • Background worker syncs automatically when connectivity returns

​
Data Quality

  • Validate coordinates before sending (lat: -90 to 90, lng: -180 to 180)
  • Include g_force_magnitude for crash detection
  • Include battery_level and network_type for analytics

​
Error Handling

  • Retry failed uploads up to 3 times with exponential backoff
  • Log sync failures for manual review
  • Keep track of sync_attempts count in local database

​
Flutter SDK Example

The Bookovia Flutter SDK handles all GPS batching and sync automatically: 
import 'package:bookovia_flutter_sdk/bookovia_flutter_sdk.dart';

// Initialize SDK
final sdk = BookoviaFlutterSDK.instance;
await sdk.initialize(BookoviaConfig(
  orgId: 'org-123',
  userId: 'user-456',
  vehicleId: 'vehicle-789',
  apiKey: 'bkv_your_api_key',
  apiBaseUrl: 'https://api.bookovia.com',
  batchSize: 100,
  syncInterval: Duration(minutes: 1),
));

// Start trip
final result = await sdk.startTracking(
  tripType: 'trip',
  purpose: 'business',
);

// SDK automatically:
// 1. Collects GPS points every 5 seconds
// 2. Buffers in SQLite
// 3. Batches 100 points
// 4. Uploads to this endpoint every 60 seconds
// 5. Marks as synced after success

​
Next Steps

Get Real-Time Mileage

Query current trip distance from DuckDB

Stop Trip

Finalize trip and calculate total mileage

Fleet Analytics

View fleet-wide performance reports

Flutter SDK

Use the official Flutter SDK for automatic GPS sync