Fleet Overview API

Authorization: Bearer YOUR_API_KEY

GET /api/v1/fleet/overview

{
  "success": true,
  "data": {
    "fleet_summary": {
      "fleet_id": "fleet_001",
      "fleet_name": "Northern Operations",
      "total_vehicles": 247,
      "active_vehicles": 198,
      "total_drivers": 185,
      "active_drivers": 142,
      "coverage_area": {
        "regions": ["North America", "Europe"],
        "countries": 12,
        "cities": 45
      }
    },
    "operational_status": {
      "vehicles_in_service": 198,
      "vehicles_idle": 31,
      "vehicles_maintenance": 12,
      "vehicles_offline": 6,
      "active_trips": 156,
      "completed_trips_today": 89,
      "utilization_rate": 80.2
    },
    "performance_metrics": {
      "total_distance_today": 12847.5,
      "total_fuel_consumed": 1247.8,
      "average_fuel_efficiency": 10.3,
      "on_time_delivery_rate": 94.7,
      "safety_score_average": 87.2,
      "cost_per_kilometer": 2.45
    },
    "vehicles": [
      {
        "vehicle_id": "vehicle_001",
        "license_plate": "ABC-123",
        "type": "delivery_truck",
        "status": "in_transit",
        "current_driver": {
          "driver_id": "driver_456",
          "name": "John Smith"
        },
        "location": {
          "latitude": 40.7128,
          "longitude": -74.0060,
          "address": "123 Main St, New York, NY",
          "last_update": "2024-03-15T14:30:00Z"
        },
        "trip_info": {
          "current_trip_id": "trip_789",
          "departure_time": "2024-03-15T09:00:00Z",
          "estimated_arrival": "2024-03-15T16:30:00Z",
          "distance_remaining": 45.2
        },
        "metrics_today": {
          "distance_driven": 187.3,
          "fuel_consumed": 18.4,
          "trips_completed": 3,
          "safety_events": 1
        }
      }
    ],
    "drivers": [
      {
        "driver_id": "driver_456",
        "name": "John Smith",
        "status": "driving",
        "assigned_vehicle": "vehicle_001",
        "license_info": {
          "license_number": "DL123456789",
          "expiry_date": "2026-12-31",
          "classifications": ["Class A", "Hazmat"]
        },
        "performance_today": {
          "trips_completed": 3,
          "distance_driven": 187.3,
          "safety_score": 92.1,
          "fuel_efficiency": 11.2,
          "on_time_rate": 100.0
        },
        "shift_info": {
          "shift_start": "2024-03-15T08:00:00Z",
          "shift_end": "2024-03-15T17:00:00Z",
          "break_time_used": 45,
          "overtime_hours": 0
        }
      }
    ],
    "maintenance_overview": {
      "vehicles_due_maintenance": 8,
      "overdue_maintenance": 2,
      "scheduled_this_week": 15,
      "total_maintenance_cost_month": 45678.90,
      "upcoming_inspections": [
        {
          "vehicle_id": "vehicle_123",
          "inspection_type": "DOT Annual",
          "due_date": "2024-03-20",
          "status": "scheduled"
        }
      ]
    },
    "analytics": {
      "trends": {
        "utilization_change": "+5.2%",
        "fuel_efficiency_change": "+3.1%",
        "safety_score_change": "+2.8%",
        "cost_efficiency_change": "-4.5%"
      },
      "benchmarks": {
        "industry_utilization": 75.0,
        "industry_safety_score": 82.5,
        "industry_fuel_efficiency": 9.8
      },
      "alerts": [
        {
          "type": "maintenance",
          "severity": "medium",
          "message": "2 vehicles overdue for maintenance",
          "action_required": true
        },
        {
          "type": "safety",
          "severity": "low",
          "message": "Safety score improved by 2.8% this month",
          "action_required": false
        }
      ]
    }
  }
}

// Fleet KPI monitoring dashboard
async function generateFleetKPIReport(fleetId, timeRange = "month") {
  const overview = await sdk.fleet.getOverview({
    fleet_id: fleetId,
    time_range: timeRange,
    include_metrics: true
  });
  
  const kpis = {
    operational_efficiency: {
      utilization_rate: overview.operational_status.utilization_rate,
      on_time_delivery: overview.performance_metrics.on_time_delivery_rate,
      cost_per_km: overview.performance_metrics.cost_per_kilometer,
      trend: overview.analytics.trends.cost_efficiency_change
    },
    safety_performance: {
      fleet_safety_score: overview.performance_metrics.safety_score_average,
      industry_benchmark: overview.analytics.benchmarks.industry_safety_score,
      improvement: overview.analytics.trends.safety_score_change,
      incidents_per_1000km: calculateIncidentRate(overview)
    },
    fuel_efficiency: {
      average_mpg: overview.performance_metrics.average_fuel_efficiency,
      industry_benchmark: overview.analytics.benchmarks.industry_fuel_efficiency,
      improvement: overview.analytics.trends.fuel_efficiency_change,
      potential_savings: calculateFuelSavings(overview)
    }
  };
  
  // Generate actionable insights
  const insights = generateActionableInsights(kpis);
  
  return {
    period: timeRange,
    fleet_name: overview.fleet_summary.fleet_name,
    kpis,
    insights,
    recommendations: generateRecommendations(kpis)
  };
}

function generateActionableInsights(kpis) {
  const insights = [];
  
  if (kpis.operational_efficiency.utilization_rate < 75) {
    insights.push({
      category: "efficiency",
      severity: "medium",
      message: "Vehicle utilization below optimal level",
      action: "Review route planning and driver schedules",
      potential_impact: "15-20% efficiency improvement"
    });
  }
  
  if (kpis.safety_performance.fleet_safety_score < kpis.safety_performance.industry_benchmark) {
    insights.push({
      category: "safety",
      severity: "high", 
      message: "Safety score below industry average",
      action: "Implement targeted driver training program",
      potential_impact: "Reduce incidents by 25-30%"
    });
  }
  
  return insights;
}

import numpy as np
from datetime import datetime, timedelta

async def predictive_maintenance_analysis(fleet_id: str):
    overview = await sdk.fleet.get_overview(
        fleet_id=fleet_id,
        include_maintenance=True,
        include_vehicles=True
    )
    
    maintenance_predictions = []
    
    for vehicle in overview.vehicles:
        # Analyze vehicle metrics
        daily_distance = vehicle.metrics_today.distance_driven
        fuel_efficiency = vehicle.metrics_today.fuel_consumed / max(daily_distance, 1)
        safety_events = vehicle.metrics_today.safety_events
        
        # Calculate wear factors
        wear_score = calculate_wear_score(vehicle)
        
        # Predict maintenance windows
        prediction = predict_next_maintenance(vehicle, wear_score)
        
        maintenance_predictions.append({
            "vehicle_id": vehicle.vehicle_id,
            "license_plate": vehicle.license_plate,
            "current_mileage": estimate_total_mileage(vehicle),
            "wear_score": wear_score,
            "predicted_maintenance": prediction,
            "priority": get_maintenance_priority(prediction),
            "estimated_cost": estimate_maintenance_cost(vehicle, prediction)
        })
    
    # Sort by urgency
    maintenance_predictions.sort(key=lambda x: x["priority"]["urgency"], reverse=True)
    
    # Generate maintenance schedule
    schedule = generate_maintenance_schedule(maintenance_predictions)
    
    return {
        "fleet_id": fleet_id,
        "analysis_date": datetime.now().isoformat(),
        "total_vehicles_analyzed": len(maintenance_predictions),
        "immediate_attention_needed": len([p for p in maintenance_predictions 
                                         if p["priority"]["urgency"] >= 8]),
        "predictions": maintenance_predictions,
        "recommended_schedule": schedule,
        "cost_projections": calculate_cost_projections(maintenance_predictions)
    }

def calculate_wear_score(vehicle):
    # Complex algorithm considering multiple factors
    base_wear = 50  # Base wear score
    
    # Distance factor
    distance_factor = min(vehicle.metrics_today.distance_driven / 200, 2.0)
    
    # Safety events increase wear
    safety_factor = vehicle.metrics_today.safety_events * 5
    
    # Fuel efficiency indicates engine health
    efficiency_factor = max(0, (12.0 - vehicle.metrics_today.fuel_consumed / 
                                max(vehicle.metrics_today.distance_driven, 1)) * 2)
    
    wear_score = base_wear + distance_factor + safety_factor + efficiency_factor
    return min(wear_score, 100)

def predict_next_maintenance(vehicle, wear_score):
    # Predict different types of maintenance
    predictions = {}
    
    # Oil change prediction
    oil_interval = 5000  # miles
    current_since_oil = estimate_miles_since_oil_change(vehicle)
    predictions["oil_change"] = {
        "miles_remaining": oil_interval - current_since_oil,
        "estimated_days": (oil_interval - current_since_oil) / 
                         max(vehicle.metrics_today.distance_driven, 50) if vehicle.metrics_today.distance_driven > 0 else 30
    }
    
    # Brake service (influenced by harsh braking events)
    brake_base_interval = 25000
    brake_wear_multiplier = 1 + (wear_score / 100) * 0.5
    predictions["brake_service"] = {
        "miles_remaining": brake_base_interval / brake_wear_multiplier,
        "estimated_days": (brake_base_interval / brake_wear_multiplier) / 
                         max(vehicle.metrics_today.distance_driven, 50) if vehicle.metrics_today.distance_driven > 0 else 180
    }
    
    return predictions

package main

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

type CostAnalysis struct {
    FleetID           string                 `json:"fleet_id"`
    AnalysisPeriod    string                 `json:"analysis_period"`
    TotalCosts        float64                `json:"total_costs"`
    CostBreakdown     CostBreakdown         `json:"cost_breakdown"`
    VehicleCosts      []VehicleCostAnalysis  `json:"vehicle_costs"`
    Optimizations     []CostOptimization     `json:"optimizations"`
    ProjectedSavings  float64                `json:"projected_savings"`
}

type CostBreakdown struct {
    FuelCosts         float64 `json:"fuel_costs"`
    MaintenanceCosts  float64 `json:"maintenance_costs"`
    LaborCosts        float64 `json:"labor_costs"`
    InsuranceCosts    float64 `json:"insurance_costs"`
    DepreciationCosts float64 `json:"depreciation_costs"`
}

func analyzeBudge_costs(ctx context.Context, client *bookovia.Client, fleetID string, timeRange string) (*CostAnalysis, error) {
    overview, err := client.Fleet.GetOverview(ctx, &bookovia.FleetOverviewRequest{
        FleetID:            fleetID,
        TimeRange:          timeRange,
        IncludeMetrics:     true,
        IncludeVehicles:    true,
        IncludeMaintenance: true,
    })
    
    if err != nil {
        return nil, fmt.Errorf("failed to get fleet overview: %w", err)
    }

    // Calculate detailed cost analysis
    costAnalysis := &CostAnalysis{
        FleetID:        fleetID,
        AnalysisPeriod: timeRange,
    }

    // Analyze costs per vehicle
    var vehicleCosts []VehicleCostAnalysis
    totalDistance := 0.0
    totalFuelCosts := 0.0
    
    for _, vehicle := range overview.Vehicles {
        vehicleCost := analyzeVehicleCosts(vehicle, overview.PerformanceMetrics)
        vehicleCosts = append(vehicleCosts, vehicleCost)
        
        totalDistance += vehicleCost.DistanceDriven
        totalFuelCosts += vehicleCost.FuelCosts
    }
    
    costAnalysis.VehicleCosts = vehicleCosts
    costAnalysis.TotalCosts = calculateTotalCosts(vehicleCosts)
    costAnalysis.CostBreakdown = calculateCostBreakdown(vehicleCosts, overview.MaintenanceOverview)
    
    // Identify optimization opportunities
    optimizations := identifyOptimizations(vehicleCosts, overview)
    costAnalysis.Optimizations = optimizations
    costAnalysis.ProjectedSavings = calculateProjectedSavings(optimizations)
    
    return costAnalysis, nil
}

func analyzeVehicleCosts(vehicle bookovia.Vehicle, metrics bookovia.PerformanceMetrics) VehicleCostAnalysis {
    distanceDriven := vehicle.MetricsToday.DistanceDriven
    fuelConsumed := vehicle.MetricsToday.FuelConsumed
    
    // Calculate various cost components
    fuelCosts := fuelConsumed * 4.50 // $4.50 per gallon average
    
    // Maintenance cost estimation based on distance and vehicle age
    maintenanceCostPerMile := 0.15 // Industry average
    maintenanceCosts := distanceDriven * maintenanceCostPerMile
    
    // Labor costs (driver wages + benefits)
    hoursOperated := estimateOperatingHours(vehicle)
    laborCosts := hoursOperated * 35.0 // $35/hour average including benefits
    
    // Depreciation (simplified calculation)
    depreciationCosts := calculateDailyDepreciation(vehicle)
    
    efficiency := distanceDriven / math.Max(fuelConsumed, 0.1)
    
    return VehicleCostAnalysis{
        VehicleID:         vehicle.VehicleID,
        LicensePlate:      vehicle.LicensePlate,
        DistanceDriven:    distanceDriven,
        FuelConsumed:      fuelConsumed,
        FuelEfficiency:    efficiency,
        FuelCosts:         fuelCosts,
        MaintenanceCosts:  maintenanceCosts,
        LaborCosts:        laborCosts,
        DepreciationCosts: depreciationCosts,
        TotalCosts:        fuelCosts + maintenanceCosts + laborCosts + depreciationCosts,
        CostPerMile:       (fuelCosts + maintenanceCosts + laborCosts + depreciationCosts) / math.Max(distanceDriven, 1),
    }
}

func identifyOptimizations(vehicleCosts []VehicleCostAnalysis, overview *bookovia.FleetOverview) []CostOptimization {
    var optimizations []CostOptimization
    
    // Sort vehicles by cost per mile to identify inefficient vehicles
    sort.Slice(vehicleCosts, func(i, j int) bool {
        return vehicleCosts[i].CostPerMile > vehicleCosts[j].CostPerMile
    })
    
    // Identify vehicles with poor fuel efficiency
    avgEfficiency := calculateAverageEfficiency(vehicleCosts)
    for _, vehicle := range vehicleCosts {
        if vehicle.FuelEfficiency < avgEfficiency*0.8 {
            optimizations = append(optimizations, CostOptimization{
                Type:           "fuel_efficiency",
                VehicleID:      vehicle.VehicleID,
                CurrentValue:   vehicle.FuelEfficiency,
                TargetValue:    avgEfficiency,
                Description:    "Improve fuel efficiency through maintenance or driver training",
                EstimatedSavings: calculateFuelSavings(vehicle, avgEfficiency),
                Priority:       "high",
            })
        }
    }
    
    // Check utilization rates
    if overview.OperationalStatus.UtilizationRate < 75.0 {
        optimizations = append(optimizations, CostOptimization{
            Type:            "utilization",
            CurrentValue:    overview.OperationalStatus.UtilizationRate,
            TargetValue:     85.0,
            Description:     "Optimize routes and schedules to increase vehicle utilization",
            EstimatedSavings: calculateUtilizationSavings(overview),
            Priority:        "medium",
        })
    }
    
    return optimizations
}

type VehicleCostAnalysis struct {
    VehicleID         string  `json:"vehicle_id"`
    LicensePlate      string  `json:"license_plate"`
    DistanceDriven    float64 `json:"distance_driven"`
    FuelConsumed      float64 `json:"fuel_consumed"`
    FuelEfficiency    float64 `json:"fuel_efficiency"`
    FuelCosts         float64 `json:"fuel_costs"`
    MaintenanceCosts  float64 `json:"maintenance_costs"`
    LaborCosts        float64 `json:"labor_costs"`
    DepreciationCosts float64 `json:"depreciation_costs"`
    TotalCosts        float64 `json:"total_costs"`
    CostPerMile       float64 `json:"cost_per_mile"`
}

type CostOptimization struct {
    Type             string  `json:"type"`
    VehicleID        string  `json:"vehicle_id,omitempty"`
    CurrentValue     float64 `json:"current_value"`
    TargetValue      float64 `json:"target_value"`
    Description      string  `json:"description"`
    EstimatedSavings float64 `json:"estimated_savings"`
    Priority         string  `json:"priority"`
}