Bookovia Telematics API Documentation

Overview

The Fleet Vehicles Management API provides complete lifecycle management for your fleet vehicles. Register new vehicles, track real-time status, manage maintenance schedules, monitor performance metrics, and analyze vehicle utilization across your entire fleet.

Authentication

All requests require authentication using your API key in the header:

Authorization: Bearer YOUR_API_KEY

Endpoints

Get Vehicle Details

GET /api/v1/fleet/vehicles/{vehicle_id}

List Fleet Vehicles

GET /api/v1/fleet/vehicles

Register New Vehicle

POST /api/v1/fleet/vehicles

Update Vehicle Information

PUT /api/v1/fleet/vehicles/{vehicle_id}

Delete Vehicle

DELETE /api/v1/fleet/vehicles/{vehicle_id}

Request Parameters

List Vehicles Query Parameters

Parameter	Type	Required	Description
`fleet_id`	string	No	Filter by specific fleet ID
`status`	string	No	Filter by vehicle status (“active”, “inactive”, “maintenance”)
`vehicle_type`	string	No	Filter by vehicle type (“truck”, “van”, “car”, “motorcycle”)
`location`	string	No	Filter by current location/region
`driver_assigned`	boolean	No	Filter vehicles with/without assigned drivers
`maintenance_due`	boolean	No	Filter vehicles due for maintenance
`limit`	integer	No	Number of vehicles to return (default: 50, max: 500)
`offset`	integer	No	Number of vehicles to skip (default: 0)
`sort_by`	string	No	Sort field (“created_at”, “license_plate”, “mileage”, “last_service”)
`sort_order`	string	No	Sort direction (“asc”, “desc”)

Vehicle Registration/Update Body

{
  "fleet_id": "fleet_001",
  "license_plate": "ABC-123",
  "vehicle_type": "delivery_truck",
  "make": "Ford",
  "model": "Transit",
  "year": 2023,
  "vin": "1FTYE2CM6NKA12345",
  "specifications": {
    "engine_type": "diesel",
    "fuel_capacity": 80.0,
    "cargo_capacity": 1200.0,
    "gross_weight": 3500.0,
    "length": 6.2,
    "width": 2.1,
    "height": 2.8
  },
  "insurance": {
    "policy_number": "POL123456789",
    "provider": "Fleet Insurance Corp",
    "expiry_date": "2024-12-31",
    "coverage_type": "comprehensive"
  },
  "registration": {
    "registration_number": "REG789012",
    "expiry_date": "2024-08-15",
    "state": "NY",
    "registration_class": "commercial"
  },
  "tracking_device": {
    "device_id": "tracker_001",
    "device_type": "GPS_OBD",
    "installation_date": "2024-01-15"
  }
}

Response Format

Individual Vehicle Response

{
  "success": true,
  "data": {
    "vehicle_id": "vehicle_001",
    "fleet_id": "fleet_001",
    "license_plate": "ABC-123",
    "vehicle_type": "delivery_truck",
    "make": "Ford",
    "model": "Transit",
    "year": 2023,
    "vin": "1FTYE2CM6NKA12345",
    "status": "active",
    "current_location": {
      "latitude": 40.7128,
      "longitude": -74.0060,
      "address": "123 Main St, New York, NY",
      "last_update": "2024-03-15T14:30:00Z"
    },
    "assigned_driver": {
      "driver_id": "driver_456",
      "name": "John Smith",
      "assignment_date": "2024-03-01T09:00:00Z"
    },
    "specifications": {
      "engine_type": "diesel",
      "fuel_capacity": 80.0,
      "cargo_capacity": 1200.0,
      "gross_weight": 3500.0,
      "dimensions": {
        "length": 6.2,
        "width": 2.1,
        "height": 2.8
      }
    },
    "odometer": {
      "current_mileage": 45678.2,
      "last_reading_date": "2024-03-15T14:30:00Z",
      "total_fleet_miles": 45678.2
    },
    "fuel_system": {
      "current_fuel_level": 75.5,
      "fuel_efficiency_avg": 12.3,
      "fuel_type": "diesel",
      "tank_capacity": 80.0
    },
    "maintenance": {
      "last_service_date": "2024-02-15T10:00:00Z",
      "last_service_mileage": 43250.0,
      "next_service_due": "2024-05-15T10:00:00Z",
      "next_service_mileage": 48250.0,
      "maintenance_status": "good",
      "upcoming_services": [
        {
          "service_type": "oil_change",
          "due_date": "2024-04-20T10:00:00Z",
          "due_mileage": 47000.0,
          "estimated_cost": 150.00
        }
      ]
    },
    "performance_metrics": {
      "today": {
        "distance_driven": 187.3,
        "fuel_consumed": 15.2,
        "trips_completed": 3,
        "average_speed": 42.5,
        "idle_time_minutes": 45,
        "harsh_events": 1
      },
      "this_week": {
        "distance_driven": 892.1,
        "fuel_consumed": 72.5,
        "trips_completed": 14,
        "utilization_rate": 78.2
      },
      "this_month": {
        "distance_driven": 3847.6,
        "fuel_consumed": 312.8,
        "trips_completed": 67,
        "maintenance_costs": 450.00
      }
    },
    "alerts": [
      {
        "type": "maintenance",
        "severity": "medium",
        "message": "Oil change due in 500 miles",
        "created_at": "2024-03-15T08:00:00Z"
      }
    ],
    "documents": {
      "insurance": {
        "policy_number": "POL123456789",
        "provider": "Fleet Insurance Corp",
        "expiry_date": "2024-12-31",
        "status": "active"
      },
      "registration": {
        "registration_number": "REG789012",
        "expiry_date": "2024-08-15",
        "state": "NY",
        "status": "valid"
      },
      "inspection": {
        "last_inspection": "2024-01-20T14:00:00Z",
        "next_inspection": "2025-01-20T14:00:00Z",
        "inspection_type": "DOT annual",
        "status": "passed"
      }
    },
    "tracking_device": {
      "device_id": "tracker_001",
      "device_type": "GPS_OBD",
      "status": "active",
      "last_communication": "2024-03-15T14:30:00Z",
      "battery_level": 95,
      "signal_strength": "strong"
    },
    "created_at": "2024-01-15T09:00:00Z",
    "updated_at": "2024-03-15T14:30:00Z"
  }
}

Vehicle List Response

{
  "success": true,
  "data": {
    "vehicles": [
      {
        "vehicle_id": "vehicle_001",
        "license_plate": "ABC-123",
        "vehicle_type": "delivery_truck",
        "make": "Ford",
        "model": "Transit",
        "status": "active",
        "current_mileage": 45678.2,
        "assigned_driver": "John Smith",
        "location": "New York, NY"
      }
    ],
    "pagination": {
      "total_count": 247,
      "returned_count": 50,
      "offset": 0,
      "limit": 50,
      "has_more": true
    },
    "summary": {
      "total_vehicles": 247,
      "active_vehicles": 198,
      "maintenance_vehicles": 12,
      "inactive_vehicles": 37,
      "average_mileage": 52341.7,
      "average_age": 3.2
    }
  }
}

SDK Examples

import { BookoviaSDK } from '@bookovia/sdk';

const sdk = new BookoviaSDK({ apiKey: 'your-api-key' });

// Get specific vehicle details
async function getVehicleDetails(vehicleId) {
  try {
    const vehicle = await sdk.fleet.vehicles.get(vehicleId);
    
    console.log(`Vehicle: ${vehicle.make} ${vehicle.model} (${vehicle.license_plate})`);
    console.log(`Status: ${vehicle.status}`);
    console.log(`Current Mileage: ${vehicle.odometer.current_mileage}`);
    console.log(`Fuel Level: ${vehicle.fuel_system.current_fuel_level}%`);
    
    // Check for maintenance alerts
    const maintenanceAlerts = vehicle.alerts.filter(alert => alert.type === 'maintenance');
    if (maintenanceAlerts.length > 0) {
      console.log('Maintenance alerts:');
      maintenanceAlerts.forEach(alert => {
        console.log(`- ${alert.message}`);
      });
    }
    
    return vehicle;
  } catch (error) {
    console.error('Failed to get vehicle details:', error);
    throw error;
  }
}

// List all vehicles with filtering
async function listFleetVehicles(options = {}) {
  try {
    const response = await sdk.fleet.vehicles.list({
      fleet_id: options.fleetId,
      status: options.status,
      vehicle_type: options.vehicleType,
      maintenance_due: options.maintenanceDue,
      limit: options.limit || 50,
      sort_by: 'license_plate',
      sort_order: 'asc'
    });
    
    console.log(`Found ${response.summary.total_vehicles} vehicles`);
    console.log(`Active: ${response.summary.active_vehicles}`);
    console.log(`In Maintenance: ${response.summary.maintenance_vehicles}`);
    
    // Display vehicles due for maintenance
    const maintenanceDue = response.vehicles.filter(vehicle => 
      vehicle.maintenance && new Date(vehicle.maintenance.next_service_due) < new Date(Date.now() + 7*24*60*60*1000)
    );
    
    if (maintenanceDue.length > 0) {
      console.log('\nVehicles due for maintenance this week:');
      maintenanceDue.forEach(vehicle => {
        console.log(`- ${vehicle.license_plate}: ${vehicle.maintenance.next_service_due}`);
      });
    }
    
    return response;
  } catch (error) {
    console.error('Failed to list vehicles:', error);
    throw error;
  }
}

// Register new vehicle
async function registerNewVehicle(vehicleData) {
  try {
    const newVehicle = await sdk.fleet.vehicles.create({
      fleet_id: vehicleData.fleetId,
      license_plate: vehicleData.licensePlate,
      vehicle_type: vehicleData.type,
      make: vehicleData.make,
      model: vehicleData.model,
      year: vehicleData.year,
      vin: vehicleData.vin,
      specifications: {
        engine_type: vehicleData.engineType,
        fuel_capacity: vehicleData.fuelCapacity,
        cargo_capacity: vehicleData.cargoCapacity
      },
      tracking_device: {
        device_id: vehicleData.trackingDeviceId,
        device_type: 'GPS_OBD'
      }
    });
    
    console.log(`Successfully registered vehicle: ${newVehicle.license_plate}`);
    console.log(`Vehicle ID: ${newVehicle.vehicle_id}`);
    
    return newVehicle;
  } catch (error) {
    console.error('Failed to register vehicle:', error);
    throw error;
  }
}

Use Cases

Fleet Expansion Planning

Analyze current fleet performance to plan vehicle additions and replacements.

// Fleet expansion analysis
async function analyzeFleetExpansion(fleetId, projectedGrowth) {
  const vehicles = await sdk.fleet.vehicles.list({
    fleet_id: fleetId,
    include_metrics: true
  });
  
  // Analyze current utilization
  const utilizationData = vehicles.vehicles.map(vehicle => ({
    vehicle_id: vehicle.vehicle_id,
    utilization_rate: calculateUtilizationRate(vehicle),
    age: new Date().getFullYear() - vehicle.year,
    maintenance_costs: vehicle.performance_metrics.this_month.maintenance_costs
  }));
  
  // Identify expansion needs
  const avgUtilization = utilizationData.reduce((sum, v) => sum + v.utilization_rate, 0) / utilizationData.length;
  const vehiclesNeedingReplacement = utilizationData.filter(v => v.age > 8 || v.maintenance_costs > 1000);
  
  const expansionPlan = {
    current_fleet_size: vehicles.summary.total_vehicles,
    target_fleet_size: Math.ceil(vehicles.summary.total_vehicles * (1 + projectedGrowth)),
    vehicles_to_add: Math.ceil(vehicles.summary.total_vehicles * projectedGrowth),
    vehicles_to_replace: vehiclesNeedingReplacement.length,
    recommended_vehicle_types: determineOptimalVehicleTypes(utilizationData),
    estimated_investment: calculateInvestmentRequired(vehiclesNeedingReplacement.length, projectedGrowth)
  };
  
  return expansionPlan;
}

function calculateUtilizationRate(vehicle) {
  const dailyDistance = vehicle.performance_metrics.today.distance_driven;
  const optimalDailyDistance = 200; // miles
  return Math.min((dailyDistance / optimalDailyDistance) * 100, 100);
}

Predictive Maintenance Scheduling

Use vehicle data to predict and schedule maintenance proactively.

import numpy as np
from datetime import datetime, timedelta

async def schedule_predictive_maintenance(fleet_id: str, days_ahead: int = 30):
    vehicles_response = await sdk.fleet.vehicles.list(
        fleet_id=fleet_id,
        include_maintenance=True
    )
    
    maintenance_schedule = []
    
    for vehicle in vehicles_response.vehicles:
        # Get detailed vehicle data
        vehicle_details = await sdk.fleet.vehicles.get(vehicle.vehicle_id)
        
        # Calculate maintenance predictions
        predictions = predict_maintenance_needs(vehicle_details, days_ahead)
        
        for prediction in predictions:
            maintenance_schedule.append({
                'vehicle_id': vehicle.vehicle_id,
                'license_plate': vehicle.license_plate,
                'maintenance_type': prediction['type'],
                'predicted_date': prediction['date'],
                'confidence': prediction['confidence'],
                'estimated_cost': prediction['cost'],
                'urgency': prediction['urgency']
            })
    
    # Sort by urgency and date
    maintenance_schedule.sort(key=lambda x: (x['urgency'], x['predicted_date']))
    
    # Generate optimized schedule
    optimized_schedule = optimize_maintenance_schedule(maintenance_schedule)
    
    return {
        'fleet_id': fleet_id,
        'schedule_period': f'{days_ahead} days',
        'total_vehicles': len(vehicles_response.vehicles),
        'maintenance_events': len(maintenance_schedule),
        'schedule': optimized_schedule,
        'cost_summary': calculate_maintenance_costs(optimized_schedule)
    }

def predict_maintenance_needs(vehicle, days_ahead):
    predictions = []
    
    current_mileage = vehicle.odometer.current_mileage
    daily_avg_miles = vehicle.performance_metrics.this_month.distance_driven / 30
    
    # Oil change prediction
    miles_since_oil = current_mileage - (vehicle.maintenance.last_service_mileage or 0)
    oil_interval = 5000
    
    if miles_since_oil + (daily_avg_miles * days_ahead) >= oil_interval:
        days_until_oil = max(1, (oil_interval - miles_since_oil) / daily_avg_miles)
        predictions.append({
            'type': 'oil_change',
            'date': (datetime.now() + timedelta(days=days_until_oil)).isoformat(),
            'confidence': 95,
            'cost': 150,
            'urgency': 'medium' if days_until_oil > 7 else 'high'
        })
    
    # Tire rotation (every 6,000 miles)
    tire_interval = 6000
    miles_since_tires = miles_since_oil  # Simplified assumption
    
    if miles_since_tires + (daily_avg_miles * days_ahead) >= tire_interval:
        days_until_tires = max(1, (tire_interval - miles_since_tires) / daily_avg_miles)
        predictions.append({
            'type': 'tire_rotation',
            'date': (datetime.now() + timedelta(days=days_until_tires)).isoformat(),
            'confidence': 85,
            'cost': 100,
            'urgency': 'low'
        })
    
    return predictions

Vehicle Performance Benchmarking

Compare vehicle performance across the fleet to identify optimization opportunities.

package main

import (
    "context"
    "fmt"
    "math"
    "sort"
)

type VehicleBenchmark struct {
    VehicleID        string  `json:"vehicle_id"`
    LicensePlate     string  `json:"license_plate"`
    FuelEfficiency   float64 `json:"fuel_efficiency"`
    UtilizationRate  float64 `json:"utilization_rate"`
    MaintenanceCost  float64 `json:"maintenance_cost"`
    SafetyScore      float64 `json:"safety_score"`
    OverallScore     float64 `json:"overall_score"`
    Rank             int     `json:"rank"`
    PerformanceGrade string  `json:"performance_grade"`
}

func benchmarkFleetPerformance(ctx context.Context, client *bookovia.Client, fleetID string) ([]VehicleBenchmark, error) {
    vehiclesResp, err := client.Fleet.Vehicles.List(ctx, &bookovia.VehicleListRequest{
        FleetID:         fleetID,
        IncludeMetrics:  true,
        Limit:           500,
    })
    
    if err != nil {
        return nil, fmt.Errorf("failed to list vehicles: %w", err)
    }

    var benchmarks []VehicleBenchmark
    
    // Calculate fleet averages for comparison
    fleetAverages := calculateFleetAverages(vehiclesResp.Vehicles)
    
    for _, vehicle := range vehiclesResp.Vehicles {
        // Get detailed vehicle data
        vehicleDetails, err := client.Fleet.Vehicles.Get(ctx, vehicle.VehicleID)
        if err != nil {
            continue
        }
        
        benchmark := VehicleBenchmark{
            VehicleID:       vehicle.VehicleID,
            LicensePlate:    vehicle.LicensePlate,
            FuelEfficiency:  calculateFuelEfficiency(vehicleDetails),
            UtilizationRate: calculateUtilizationRate(vehicleDetails),
            MaintenanceCost: vehicleDetails.PerformanceMetrics.ThisMonth.MaintenanceCosts,
            SafetyScore:     calculateSafetyScore(vehicleDetails),
        }
        
        // Calculate overall performance score
        benchmark.OverallScore = calculateOverallScore(benchmark, fleetAverages)
        benchmarks = append(benchmarks, benchmark)
    }
    
    // Sort by overall score
    sort.Slice(benchmarks, func(i, j int) bool {
        return benchmarks[i].OverallScore > benchmarks[j].OverallScore
    })
    
    // Assign ranks and grades
    for i := range benchmarks {
        benchmarks[i].Rank = i + 1
        benchmarks[i].PerformanceGrade = assignPerformanceGrade(benchmarks[i].OverallScore)
    }
    
    return benchmarks, nil
}

type FleetAverages struct {
    FuelEfficiency  float64
    UtilizationRate float64
    MaintenanceCost float64
    SafetyScore     float64
}

func calculateFleetAverages(vehicles []bookovia.VehicleSummary) FleetAverages {
    var totalFuel, totalUtil, totalMaint, totalSafety float64
    count := float64(len(vehicles))
    
    for _, vehicle := range vehicles {
        // These would be calculated from actual vehicle data
        totalFuel += 12.0  // Placeholder
        totalUtil += 80.0  // Placeholder
        totalMaint += 500.0 // Placeholder
        totalSafety += 85.0 // Placeholder
    }
    
    return FleetAverages{
        FuelEfficiency:  totalFuel / count,
        UtilizationRate: totalUtil / count,
        MaintenanceCost: totalMaint / count,
        SafetyScore:     totalSafety / count,
    }
}

func calculateOverallScore(benchmark VehicleBenchmark, averages FleetAverages) float64 {
    // Weighted score calculation
    fuelWeight := 0.3
    utilWeight := 0.3
    maintWeight := 0.2
    safetyWeight := 0.2
    
    // Normalize scores (higher is better, except maintenance cost)
    fuelScore := (benchmark.FuelEfficiency / averages.FuelEfficiency) * 100
    utilScore := (benchmark.UtilizationRate / averages.UtilizationRate) * 100
    maintScore := (averages.MaintenanceCost / benchmark.MaintenanceCost) * 100 // Inverted
    safetyScore := (benchmark.SafetyScore / averages.SafetyScore) * 100
    
    return (fuelScore * fuelWeight) + 
           (utilScore * utilWeight) + 
           (maintScore * maintWeight) + 
           (safetyScore * safetyWeight)
}

func assignPerformanceGrade(score float64) string {
    switch {
    case score >= 120:
        return "A+"
    case score >= 110:
        return "A"
    case score >= 100:
        return "B+"
    case score >= 90:
        return "B"
    case score >= 80:
        return "C+"
    case score >= 70:
        return "C"
    default:
        return "D"
    }
}

Error Handling

Status Code	Error Type	Description
400	`INVALID_PARAMETERS`	Invalid request parameters
401	`UNAUTHORIZED`	Invalid or missing API key
403	`FORBIDDEN`	No access to specified fleet or vehicle
404	`VEHICLE_NOT_FOUND`	Specified vehicle ID does not exist
404	`FLEET_NOT_FOUND`	Specified fleet ID does not exist
409	`DUPLICATE_LICENSE_PLATE`	License plate already exists in system
422	`INVALID_VIN`	Invalid VIN format or checksum
429	`RATE_LIMIT_EXCEEDED`	Too many requests
500	`INTERNAL_ERROR`	Server error processing request

Best Practices

Vehicle Registration

Always validate VIN checksums before registration
Ensure license plates are unique within your system
Include comprehensive vehicle specifications for better analytics
Set up tracking devices during initial registration

Data Management

Implement regular data synchronization for vehicle metrics
Use consistent naming conventions for vehicle types
Maintain accurate maintenance records for predictive analytics
Regular cleanup of inactive or decommissioned vehicles

Performance Monitoring

Set up automated alerts for maintenance due dates
Monitor utilization rates to optimize fleet size
Track fuel efficiency trends for cost management
Implement safety score monitoring for driver training

Security and Privacy

Protect sensitive vehicle and location data
Implement proper access controls for vehicle management
Regular backup of vehicle registration and history data
Comply with data retention regulations

Related Endpoints

Explore other fleet management capabilities:

Fleet Overview API - Fleet dashboard
Fleet Utilization API - Usage analytics
Fleet Optimization API - Route optimization
Trip Management API - Trip operations

Trip Management

Routing & Navigation

Maps & Vector Tiles

Geocoding & Places

Location Data

Safety Analytics

Fleet Management

Real-time Streaming

Device Management

Emergency & Alerts

Fleet Vehicles Management API

Overview

Authentication

Endpoints

Get Vehicle Details

List Fleet Vehicles

Register New Vehicle

Update Vehicle Information

Delete Vehicle

Request Parameters

List Vehicles Query Parameters

Vehicle Registration/Update Body

Response Format

Individual Vehicle Response

Vehicle List Response

SDK Examples

Use Cases

Fleet Expansion Planning

Predictive Maintenance Scheduling

Vehicle Performance Benchmarking

Error Handling

Best Practices

Vehicle Registration

Data Management

Performance Monitoring

Security and Privacy

Related Endpoints

Trip Management

Routing & Navigation

Maps & Vector Tiles

Geocoding & Places

Location Data

Safety Analytics

Fleet Management

Real-time Streaming

Device Management

Emergency & Alerts

Documentation Index

​Overview

​Authentication

​Endpoints

​Get Vehicle Details

​List Fleet Vehicles

​Register New Vehicle

​Update Vehicle Information

​Delete Vehicle

​Request Parameters

​List Vehicles Query Parameters

​Vehicle Registration/Update Body

​Response Format

​Individual Vehicle Response

​Vehicle List Response

​SDK Examples

​Use Cases

​Fleet Expansion Planning

​Predictive Maintenance Scheduling

​Vehicle Performance Benchmarking

​Error Handling

​Best Practices

​Vehicle Registration

​Data Management

​Performance Monitoring

​Security and Privacy

Related Endpoints

Overview

Authentication

Endpoints

Get Vehicle Details

List Fleet Vehicles

Register New Vehicle

Update Vehicle Information

Delete Vehicle

Request Parameters

List Vehicles Query Parameters

Vehicle Registration/Update Body

Response Format

Individual Vehicle Response

Vehicle List Response

SDK Examples

Use Cases

Fleet Expansion Planning

Predictive Maintenance Scheduling

Vehicle Performance Benchmarking

Error Handling

Best Practices

Vehicle Registration

Data Management

Performance Monitoring

Security and Privacy