Skip to main content
GET
/
v1
/
trips
/
{trip_id}
/
summary
Get Trip Summary
curl --request GET \
  --url https://api.bookovia.com/v1/trips/{trip_id}/summary \
  --header 'X-API-Key: <api-key>'
{
  "error": {
    "code": "trip_not_found",
    "message": "The specified trip_id was not found"
  }
}

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 Get Trip Summary endpoint provides detailed analytics, performance metrics, and insights for completed trips. This endpoint is optimized for reporting and includes advanced analytics like safety scoring, eco-driving metrics, and comparative benchmarks.
This endpoint is primarily designed for completed trips. Active trips will return partial analytics.

​
Authentication

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

​
Request

​
trip_id
string
required
Unique identifier for the trip to get summary for
​
include_benchmarks
boolean
default:"false"
Whether to include performance benchmarks compared to organization averages
​
include_route_analysis
boolean
default:"true"
Whether to include detailed route analysis and optimization suggestions
​
export_format
string
default:"json"
Response format. Options: “json”, “pdf_url” (generates downloadable PDF report)

​
Request Example

curl -X GET "https://api.bookovia.com/v1/trips/trip_1234567890abcdef/summary?include_benchmarks=true" \
  -H "X-API-Key: bkv_test_your_api_key_here"

​
Response

​
trip_id
string
Unique identifier for the trip
​
summary_generated_at
string
ISO 8601 timestamp when this summary was generated
​
trip_overview
object
Basic trip information and metrics
​
performance_metrics
object
Detailed performance and efficiency metrics
​
driving_behavior
object
Detailed analysis of driving behavior and events
​
fuel_analysis
object
Fuel consumption and efficiency analysis
​
route_analysis
object
Route optimization and efficiency analysis

​
Success Response

{
  "trip_id": "trip_1234567890abcdef",
  "summary_generated_at": "2024-04-13T12:30:00Z",
  "trip_overview": {
    "vehicle_id": "vehicle_123",
    "driver_id": "driver_456",
    "start_time": "2024-04-13T10:30:00Z",
    "end_time": "2024-04-13T12:15:00Z",
    "duration_minutes": 105,
    "distance_km": 45.2,
    "status": "completed",
    "purpose": "delivery"
  },
  "performance_metrics": {
    "safety_score": 87,
    "eco_score": 82,
    "efficiency_score": 91,
    "avg_speed_kmh": 32.4,
    "max_speed_kmh": 85,
    "idle_time_minutes": 8.5,
    "moving_time_minutes": 96.5,
    "stops_count": 3,
    "total_events": 3
  },
  "driving_behavior": {
    "harsh_events": {
      "harsh_acceleration": {
        "count": 1,
        "severity": "moderate",
        "impact_on_score": -2
      },
      "harsh_braking": {
        "count": 2,
        "severity": "moderate", 
        "impact_on_score": -4
      },
      "harsh_cornering": {
        "count": 0,
        "severity": null,
        "impact_on_score": 0
      }
    },
    "speeding_analysis": {
      "incidents_count": 0,
      "time_over_limit_minutes": 0,
      "max_speed_over_limit_kmh": 0,
      "impact_on_score": 0
    },
    "smoothness_score": 89,
    "consistency_score": 85,
    "distraction_indicators": []
  },
  "fuel_analysis": {
    "fuel_consumed_liters": 4.2,
    "fuel_efficiency_kmpl": 10.8,
    "co2_emissions_kg": 9.8,
    "efficiency_rating": "good",
    "cost_estimate": {
      "fuel_cost_usd": 6.30,
      "currency": "USD"
    },
    "efficiency_factors": {
      "aggressive_driving_impact": -5,
      "traffic_impact": -8,
      "route_efficiency_impact": 2
    }
  },
  "route_analysis": {
    "planned_vs_actual": {
      "planned_distance_km": 43.8,
      "actual_distance_km": 45.2,
      "variance_percentage": 3.2,
      "efficiency_rating": "good"
    },
    "traffic_impact": {
      "delay_minutes": 12,
      "congestion_percentage": 15,
      "peak_hours_overlap": true
    },
    "optimization_suggestions": [
      {
        "type": "route",
        "suggestion": "Alternative route via Highway 95 could save 3.2 km",
        "potential_savings": {
          "distance_km": 3.2,
          "time_minutes": 8,
          "fuel_liters": 0.3
        }
      },
      {
        "type": "timing",
        "suggestion": "Departing 30 minutes earlier could avoid peak traffic",
        "potential_savings": {
          "time_minutes": 15,
          "fuel_liters": 0.4
        }
      }
    ]
  },
  "benchmarks": {
    "vs_organization_average": {
      "safety_score": {
        "trip_score": 87,
        "org_average": 82,
        "percentile": 75
      },
      "fuel_efficiency": {
        "trip_efficiency": 10.8,
        "org_average": 9.2,
        "percentile": 80
      }
    },
    "vs_similar_routes": {
      "efficiency_percentile": 68,
      "safety_percentile": 85,
      "time_percentile": 45
    }
  },
  "recommendations": [
    {
      "category": "safety",
      "priority": "medium",
      "title": "Reduce harsh braking events",
      "description": "Two moderate harsh braking events were detected. Maintaining greater following distance could help.",
      "potential_improvement": "2-3 point safety score increase"
    },
    {
      "category": "efficiency",
      "priority": "low", 
      "title": "Optimize departure time",
      "description": "Departing during off-peak hours could improve fuel efficiency.",
      "potential_improvement": "5-8% fuel savings"
    }
  ]
}

​
Error Responses

{
  "error": {
    "code": "trip_not_found",
    "message": "The specified trip_id was not found"
  }
}

​
SDK Examples

import Bookovia from '@bookovia/javascript-sdk';

const client = new Bookovia('bkv_test_your_api_key');

const summary = await client.trips.getSummary('trip_1234567890abcdef', {
  includeBenchmarks: true,
  includeRouteAnalysis: true
});

console.log(`Safety Score: ${summary.performanceMetrics.safetyScore}`);
console.log(`Fuel Efficiency: ${summary.fuelAnalysis.fuelEfficiencyKmpl} km/L`);

// Generate PDF report
const pdfReport = await client.trips.getSummary('trip_1234567890abcdef', {
  exportFormat: 'pdf_url'
});
console.log(`PDF Report: ${pdfReport.download_url}`);

​
Use Cases

​
Driver Performance Review

const generateDriverReport = async (driverId, tripIds) => {
  const summaries = await Promise.all(
    tripIds.map(id => client.trips.getSummary(id, { includeBenchmarks: true }))
  );
  
  const avgSafetyScore = summaries.reduce((sum, s) => 
    sum + s.performanceMetrics.safetyScore, 0) / summaries.length;
  
  return {
    driverId,
    avgSafetyScore,
    totalTrips: summaries.length,
    recommendations: summaries.flatMap(s => s.recommendations)
  };
};

​
Fleet Efficiency Analysis

async def analyze_fleet_efficiency(organization_id, date_range):
    trips = await client.trips.list(
        organization_id=organization_id,
        date_range=date_range
    )
    
    summaries = []
    for trip in trips:
        summary = await client.trips.get_summary(trip.trip_id)
        summaries.append(summary)
    
    avg_efficiency = sum(s.fuel_analysis.fuel_efficiency_kmpl for s in summaries) / len(summaries)
    total_emissions = sum(s.fuel_analysis.co2_emissions_kg for s in summaries)
    
    return {
        'avg_efficiency': avg_efficiency,
        'total_emissions': total_emissions,
        'fleet_size': len(summaries)
    }

​
Next Steps

List Trips

Get multiple trip summaries for analysis

Safety Analytics

Deep dive into safety analytics

Behavior Analysis

Advanced driving behavior analysis

Fleet Reports

Organization-wide fleet analytics