Fleet Utilization Analytics API

Authorization: Bearer YOUR_API_KEY

GET /api/v1/fleet/utilization

{
  "success": true,
  "data": {
    "analysis_summary": {
      "fleet_id": "fleet_001",
      "analysis_period": "month",
      "total_vehicles": 247,
      "analyzed_vehicles": 198,
      "analysis_date_range": {
        "start_date": "2024-02-15T00:00:00Z",
        "end_date": "2024-03-15T23:59:59Z"
      }
    },
    "overall_utilization": {
      "fleet_utilization_rate": 78.3,
      "target_utilization_rate": 85.0,
      "utilization_grade": "B+",
      "efficiency_score": 82.1,
      "improvement_potential": 8.7
    },
    "vehicle_utilization": {
      "average_utilization": 78.3,
      "high_performers": 45,
      "underutilized": 28,
      "idle_vehicles": 12,
      "utilization_distribution": {
        "90-100%": 23,
        "80-89%": 45,
        "70-79%": 67,
        "60-69%": 34,
        "below_60%": 29
      }
    },
    "temporal_analysis": {
      "hourly_utilization": [
        {
          "hour": 0,
          "utilization_rate": 12.5,
          "active_vehicles": 25
        },
        {
          "hour": 8,
          "utilization_rate": 89.2,
          "active_vehicles": 176
        }
      ],
      "daily_utilization": [
        {
          "day": "monday",
          "utilization_rate": 85.2,
          "efficiency_score": 88.1
        }
      ],
      "peak_hours": {
        "morning_peak": "08:00-10:00",
        "afternoon_peak": "14:00-17:00",
        "peak_utilization": 92.3
      }
    },
    "route_efficiency": {
      "total_distance": 45672.8,
      "productive_distance": 38421.2,
      "deadhead_distance": 7251.6,
      "deadhead_percentage": 15.9,
      "route_optimization_score": 84.1,
      "fuel_efficiency": 11.2
    },
    "driver_productivity": {
      "active_drivers": 142,
      "average_trips_per_driver": 3.2,
      "average_distance_per_driver": 187.3,
      "productivity_score": 79.8,
      "top_performers": [
        {
          "driver_id": "driver_456",
          "name": "John Smith",
          "trips_completed": 5,
          "distance_covered": 287.5,
          "efficiency_rating": 94.2
        }
      ]
    },
    "detailed_breakdown": [
      {
        "vehicle_id": "vehicle_001",
        "license_plate": "ABC-123",
        "utilization_metrics": {
          "utilization_rate": 87.5,
          "active_hours": 8.7,
          "idle_hours": 1.3,
          "total_distance": 234.7,
          "revenue_distance": 201.3,
          "efficiency_score": 91.2
        },
        "performance_indicators": {
          "trips_completed": 4,
          "on_time_percentage": 95.0,
          "fuel_efficiency": 12.8,
          "safety_incidents": 0
        }
      }
    ],
    "improvement_opportunities": [
      {
        "category": "route_optimization",
        "description": "Reduce deadhead miles through better route planning",
        "potential_improvement": "12% efficiency increase",
        "affected_vehicles": 23,
        "estimated_savings": "$1,450/month"
      },
      {
        "category": "vehicle_scheduling",
        "description": "Better utilization of underused vehicles",
        "potential_improvement": "8% utilization increase",
        "affected_vehicles": 28,
        "estimated_savings": "$2,100/month"
      }
    ],
    "benchmarks": {
      "industry_average_utilization": 72.0,
      "best_in_class_utilization": 88.0,
      "your_performance_vs_industry": "+6.3%",
      "your_performance_vs_best": "-9.7%"
    },
    "cost_analysis": {
      "total_operating_cost": 87654.32,
      "cost_per_mile": 1.92,
      "underutilization_cost": 8970.45,
      "optimization_savings_potential": 12450.67
    }
  }
}

// Dynamic route optimization using utilization data
async function optimizeRoutesBasedOnUtilization(fleetId) {
  const analysis = await sdk.fleet.utilization.analyze({
    fleet_id: fleetId,
    time_range: "today",
    group_by: "time_period"
  });
  
  // Identify underutilized time periods
  const lowUtilizationHours = analysis.temporal_analysis.hourly_utilization
    .filter(hour => hour.utilization_rate < 60 && hour.hour >= 8 && hour.hour <= 18)
    .map(hour => hour.hour);
  
  // Get vehicles with low utilization during these hours
  const underutilizedVehicles = analysis.detailed_breakdown
    .filter(vehicle => vehicle.utilization_metrics.utilization_rate < 70)
    .sort((a, b) => a.utilization_metrics.utilization_rate - b.utilization_metrics.utilization_rate);
  
  // Generate optimization recommendations
  const optimizations = [];
  
  for (const vehicle of underutilizedVehicles.slice(0, 10)) {
    // Analyze current routes
    const currentEfficiency = vehicle.utilization_metrics.efficiency_score;
    const idleHours = vehicle.utilization_metrics.idle_hours;
    
    if (idleHours > 2) {
      optimizations.push({
        vehicle_id: vehicle.vehicle_id,
        current_utilization: vehicle.utilization_metrics.utilization_rate,
        recommendation: 'add_delivery_stops',
        details: `Add ${Math.floor(idleHours)} additional stops during idle periods`,
        potential_improvement: `+${Math.floor(idleHours * 15)}% utilization`,
        implementation_priority: currentEfficiency < 70 ? 'high' : 'medium'
      });
    }
    
    if (vehicle.utilization_metrics.revenue_distance / vehicle.utilization_metrics.total_distance < 0.8) {
      optimizations.push({
        vehicle_id: vehicle.vehicle_id,
        current_utilization: vehicle.utilization_metrics.utilization_rate,
        recommendation: 'reduce_deadhead_miles',
        details: 'Optimize route sequence to minimize empty miles',
        potential_improvement: '+20% efficiency',
        implementation_priority: 'high'
      });
    }
  }
  
  return {
    analysis_date: new Date().toISOString(),
    fleet_id: fleetId,
    optimization_opportunities: optimizations.length,
    total_vehicles_analyzed: underutilizedVehicles.length,
    optimizations: optimizations,
    estimated_improvement: calculateEstimatedImprovement(optimizations)
  };
}

function calculateEstimatedImprovement(optimizations) {
  const totalImpact = optimizations.reduce((sum, opt) => {
    const improvement = parseFloat(opt.potential_improvement.match(/\d+/)[0]);
    return sum + improvement;
  }, 0);
  
  return {
    average_utilization_increase: totalImpact / optimizations.length,
    total_efficiency_gain: `${totalImpact}%`,
    estimated_cost_savings: totalImpact * 50 // $50 per percentage point improvement
  };
}

import numpy as np
from sklearn.linear_model import LinearRegression
from datetime import datetime, timedelta

async def predict_utilization_trends(fleet_id: str, prediction_days: int = 30):
    # Get historical utilization data
    historical_analysis = []
    
    for i in range(90):  # Last 90 days
        date = datetime.now() - timedelta(days=i)
        try:
            daily_analysis = await sdk.fleet.utilization.analyze(
                fleet_id=fleet_id,
                time_range="day",
                analysis_date=date.isoformat()
            )
            historical_analysis.append({
                'date': date,
                'utilization_rate': daily_analysis.overall_utilization.fleet_utilization_rate,
                'efficiency_score': daily_analysis.overall_utilization.efficiency_score,
                'active_vehicles': daily_analysis.vehicle_utilization.high_performers + 
                                daily_analysis.vehicle_utilization.underutilized
            })
        except Exception:
            continue
    
    if len(historical_analysis) < 30:
        raise ValueError("Insufficient historical data for prediction")
    
    # Prepare data for modeling
    X = np.array([[i, data['active_vehicles']] for i, data in enumerate(historical_analysis)])
    y_utilization = np.array([data['utilization_rate'] for data in historical_analysis])
    y_efficiency = np.array([data['efficiency_score'] for data in historical_analysis])
    
    # Train prediction models
    utilization_model = LinearRegression().fit(X, y_utilization)
    efficiency_model = LinearRegression().fit(X, y_efficiency)
    
    # Generate predictions
    predictions = []
    current_active_vehicles = historical_analysis[0]['active_vehicles']
    
    for day in range(prediction_days):
        future_day = len(historical_analysis) + day
        X_future = np.array([[future_day, current_active_vehicles]])
        
        predicted_utilization = utilization_model.predict(X_future)[0]
        predicted_efficiency = efficiency_model.predict(X_future)[0]
        
        # Apply seasonal adjustments
        seasonal_factor = get_seasonal_factor(datetime.now() + timedelta(days=day))
        adjusted_utilization = predicted_utilization * seasonal_factor
        
        predictions.append({
            'date': (datetime.now() + timedelta(days=day)).isoformat(),
            'predicted_utilization': max(0, min(100, adjusted_utilization)),
            'predicted_efficiency': max(0, min(100, predicted_efficiency)),
            'confidence_interval': calculate_confidence_interval(predicted_utilization, day),
            'recommended_actions': generate_proactive_actions(adjusted_utilization, predicted_efficiency)
        })
    
    return {
        'fleet_id': fleet_id,
        'prediction_period': f'{prediction_days} days',
        'model_accuracy': calculate_model_accuracy(utilization_model, X, y_utilization),
        'historical_data_points': len(historical_analysis),
        'predictions': predictions,
        'trend_analysis': analyze_trends(predictions),
        'optimization_recommendations': generate_optimization_recommendations(predictions)
    }

def get_seasonal_factor(date):
    """Adjust for seasonal patterns"""
    month = date.month
    day_of_week = date.weekday()
    
    # Monthly seasonal factors
    seasonal_factors = {
        1: 0.85,   # January - lower activity
        2: 0.90,   # February
        3: 1.05,   # March - spring increase
        4: 1.10,   # April
        5: 1.15,   # May - peak season
        6: 1.20,   # June
        7: 1.15,   # July
        8: 1.10,   # August
        9: 1.05,   # September
        10: 1.00,  # October
        11: 0.95,  # November
        12: 0.80   # December - holiday slowdown
    }
    
    # Weekly patterns
    weekly_factors = [0.8, 1.1, 1.1, 1.1, 1.1, 1.0, 0.7]  # Mon-Sun
    
    return seasonal_factors.get(month, 1.0) * weekly_factors[day_of_week]

def generate_proactive_actions(utilization, efficiency):
    """Generate proactive recommendations based on predictions"""
    actions = []
    
    if utilization < 70:
        actions.append({
            'action': 'increase_marketing',
            'description': 'Boost marketing efforts to increase demand',
            'urgency': 'medium',
            'timeline': 'within 1 week'
        })
        
        actions.append({
            'action': 'temporary_fleet_reduction',
            'description': 'Consider temporary vehicle reallocation',
            'urgency': 'low',
            'timeline': 'within 2 weeks'
        })
    
    if utilization > 95:
        actions.append({
            'action': 'capacity_expansion',
            'description': 'Prepare for potential capacity constraints',
            'urgency': 'high',
            'timeline': 'immediate'
        })
    
    if efficiency < 75:
        actions.append({
            'action': 'route_optimization',
            'description': 'Implement advanced route optimization',
            'urgency': 'medium',
            'timeline': 'within 1 week'
        })
    
    return actions

package main

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

type FleetSizingAnalysis struct {
    CurrentFleetSize     int                    `json:"current_fleet_size"`
    OptimalFleetSize     int                    `json:"optimal_fleet_size"`
    SizingRecommendation FleetSizingRecommendation `json:"sizing_recommendation"`
    CostImpact          CostImpactAnalysis      `json:"cost_impact"`
    ImplementationPlan   []SizingAction         `json:"implementation_plan"`
}

type FleetSizingRecommendation struct {
    Action              string  `json:"action"`
    VehicleAdjustment   int     `json:"vehicle_adjustment"`
    ConfidenceLevel     float64 `json:"confidence_level"`
    RecommendationBasis string  `json:"recommendation_basis"`
}

func analyzeFleetSizing(ctx context.Context, client *bookovia.Client, fleetID string) (*FleetSizingAnalysis, error) {
    // Get comprehensive utilization data
    utilizationAnalysis, err := client.Fleet.Utilization.Analyze(ctx, &bookovia.UtilizationRequest{
        FleetID:           fleetID,
        TimeRange:         "quarter", // Quarterly analysis for better insights
        IncludeDetails:    true,
        IncludeBenchmarks: true,
    })
    
    if err != nil {
        return nil, fmt.Errorf("failed to get utilization analysis: %w", err)
    }

    // Calculate optimal fleet size
    optimalSize := calculateOptimalFleetSize(utilizationAnalysis)
    
    // Generate recommendations
    recommendation := generateSizingRecommendation(utilizationAnalysis.AnalysisSummary.TotalVehicles, optimalSize)
    
    // Analyze cost impact
    costImpact := analyzeCostImpact(utilizationAnalysis, optimalSize)
    
    // Create implementation plan
    implementationPlan := createSizingImplementationPlan(recommendation, utilizationAnalysis)
    
    return &FleetSizingAnalysis{
        CurrentFleetSize:     utilizationAnalysis.AnalysisSummary.TotalVehicles,
        OptimalFleetSize:     optimalSize,
        SizingRecommendation: recommendation,
        CostImpact:          costImpact,
        ImplementationPlan:   implementationPlan,
    }, nil
}

func calculateOptimalFleetSize(analysis *bookovia.UtilizationAnalysis) int {
    currentSize := analysis.AnalysisSummary.TotalVehicles
    currentUtilization := analysis.OverallUtilization.FleetUtilizationRate
    targetUtilization := 85.0 // Target utilization rate
    
    // Base calculation on utilization
    utilizationBasedSize := float64(currentSize) * (currentUtilization / targetUtilization)
    
    // Factor in demand patterns
    demandVariability := calculateDemandVariability(analysis)
    bufferFactor := 1.0 + (demandVariability * 0.1) // 10% buffer per variability unit
    
    // Account for growth trends
    growthFactor := estimateGrowthFactor(analysis)
    
    optimalSize := int(math.Round(utilizationBasedSize * bufferFactor * growthFactor))
    
    // Ensure reasonable bounds
    minSize := int(float64(currentSize) * 0.7) // Don't reduce more than 30%
    maxSize := int(float64(currentSize) * 1.5) // Don't increase more than 50%
    
    if optimalSize < minSize {
        optimalSize = minSize
    }
    if optimalSize > maxSize {
        optimalSize = maxSize
    }
    
    return optimalSize
}

func calculateDemandVariability(analysis *bookovia.UtilizationAnalysis) float64 {
    // Calculate coefficient of variation in daily utilization
    dailyRates := []float64{}
    for _, daily := range analysis.TemporalAnalysis.DailyUtilization {
        dailyRates = append(dailyRates, daily.UtilizationRate)
    }
    
    if len(dailyRates) == 0 {
        return 0.2 // Default variability
    }
    
    mean := calculateMean(dailyRates)
    stdDev := calculateStandardDeviation(dailyRates, mean)
    
    return stdDev / mean // Coefficient of variation
}

func estimateGrowthFactor(analysis *bookovia.UtilizationAnalysis) float64 {
    // Simple growth estimation based on recent trends
    // In a real implementation, this would use more sophisticated forecasting
    
    dailyRates := []float64{}
    for _, daily := range analysis.TemporalAnalysis.DailyUtilization {
        dailyRates = append(dailyRates, daily.UtilizationRate)
    }
    
    if len(dailyRates) < 30 {
        return 1.05 // Default 5% growth assumption
    }
    
    // Calculate trend over last 30 days
    recentTrend := (dailyRates[0] - dailyRates[29]) / dailyRates[29]
    
    // Annualize the trend and cap at reasonable levels
    annualizedGrowth := recentTrend * 12 // Monthly to annual
    
    // Cap growth between -20% and +50%
    if annualizedGrowth < -0.2 {
        annualizedGrowth = -0.2
    }
    if annualizedGrowth > 0.5 {
        annualizedGrowth = 0.5
    }
    
    return 1.0 + annualizedGrowth
}

func generateSizingRecommendation(currentSize, optimalSize int) FleetSizingRecommendation {
    adjustment := optimalSize - currentSize
    
    var action string
    var confidence float64
    var basis string
    
    if adjustment > 5 {
        action = "expand"
        confidence = 0.8
        basis = "High utilization indicates demand exceeds current capacity"
    } else if adjustment < -5 {
        action = "reduce"
        confidence = 0.75
        basis = "Low utilization suggests fleet overcapacity"
    } else {
        action = "maintain"
        confidence = 0.9
        basis = "Current fleet size is near optimal"
    }
    
    return FleetSizingRecommendation{
        Action:              action,
        VehicleAdjustment:   adjustment,
        ConfidenceLevel:     confidence,
        RecommendationBasis: basis,
    }
}

type CostImpactAnalysis struct {
    CurrentAnnualCost   float64 `json:"current_annual_cost"`
    OptimizedAnnualCost float64 `json:"optimized_annual_cost"`
    AnnualSavings      float64 `json:"annual_savings"`
    PaybackPeriodMonths int     `json:"payback_period_months"`
    ROI                float64 `json:"roi"`
}

func analyzeCostImpact(analysis *bookovia.UtilizationAnalysis, optimalSize int) CostImpactAnalysis {
    currentSize := analysis.AnalysisSummary.TotalVehicles
    
    // Cost assumptions (would be configurable in real implementation)
    vehicleAnnualCost := 25000.0 // Annual cost per vehicle
    utilizationCostFactor := 0.1  // Additional cost per % under-utilization
    
    currentAnnualCost := float64(currentSize) * vehicleAnnualCost
    optimizedAnnualCost := float64(optimalSize) * vehicleAnnualCost
    
    // Factor in utilization efficiency gains
    currentUtilization := analysis.OverallUtilization.FleetUtilizationRate
    targetUtilization := 85.0
    
    utilizationPenalty := math.Max(0, (targetUtilization - currentUtilization) / 100.0 * currentAnnualCost * utilizationCostFactor)
    currentAnnualCost += utilizationPenalty
    
    annualSavings := currentAnnualCost - optimizedAnnualCost
    
    // Calculate ROI and payback period
    implementationCost := math.Abs(float64(optimalSize - currentSize)) * 5000.0 // $5k per vehicle change
    roi := annualSavings / implementationCost
    paybackMonths := int(implementationCost / (annualSavings / 12.0))
    
    return CostImpactAnalysis{
        CurrentAnnualCost:   currentAnnualCost,
        OptimizedAnnualCost: optimizedAnnualCost,
        AnnualSavings:      annualSavings,
        PaybackPeriodMonths: paybackMonths,
        ROI:                roi,
    }
}

type SizingAction struct {
    Phase       int    `json:"phase"`
    Action      string `json:"action"`
    Timeline    string `json:"timeline"`
    VehicleCount int   `json:"vehicle_count"`
    Priority    string `json:"priority"`
}

func createSizingImplementationPlan(recommendation FleetSizingRecommendation, analysis *bookovia.UtilizationAnalysis) []SizingAction {
    var actions []SizingAction
    
    adjustment := recommendation.VehicleAdjustment
    
    if adjustment == 0 {
        return actions // No changes needed
    }
    
    // Phase the implementation to reduce risk
    if math.Abs(float64(adjustment)) <= 5 {
        // Small adjustment - single phase
        actions = append(actions, SizingAction{
            Phase:       1,
            Action:      recommendation.Action,
            Timeline:    "within 1 month",
            VehicleCount: int(math.Abs(float64(adjustment))),
            Priority:    "medium",
        })
    } else {
        // Large adjustment - multiple phases
        phaseSize := int(math.Ceil(math.Abs(float64(adjustment)) / 3.0))
        remaining := int(math.Abs(float64(adjustment)))
        
        for phase := 1; remaining > 0; phase++ {
            vehicleCount := int(math.Min(float64(phaseSize), float64(remaining)))
            
            var timeline string
            var priority string
            
            switch phase {
            case 1:
                timeline = "within 1 month"
                priority = "high"
            case 2:
                timeline = "within 3 months"
                priority = "medium"
            default:
                timeline = "within 6 months"
                priority = "low"
            }
            
            actions = append(actions, SizingAction{
                Phase:       phase,
                Action:      recommendation.Action,
                Timeline:    timeline,
                VehicleCount: vehicleCount,
                Priority:    priority,
            })
            
            remaining -= vehicleCount
        }
    }
    
    return actions
}

// Utility functions
func calculateMean(values []float64) float64 {
    sum := 0.0
    for _, v := range values {
        sum += v
    }
    return sum / float64(len(values))
}

func calculateStandardDeviation(values []float64, mean float64) float64 {
    variance := 0.0
    for _, v := range values {
        variance += math.Pow(v - mean, 2)
    }
    variance /= float64(len(values))
    return math.Sqrt(variance)
}