Trips

Trips are the core building block of the Bookovia Telematics API. A trip represents a single vehicle journey from start to stop, capturing all location data, analytics, and events that occur during that time period.

What is a Trip?

A trip represents a complete vehicle journey with the following characteristics:

Start Point: When and where the journey begins
End Point: When and where the journey concludes
Route: The path taken between start and end points
Duration: Total time from start to stop
Distance: Total distance traveled
Analytics: Speed, acceleration, safety metrics, and driver behavior
Events: Significant occurrences during the trip (harsh braking, speeding, etc.)

Trip Lifecycle

1. Trip Creation

Trips are created by calling the start trip endpoint:

curl -X POST https://api.bookovia.com/v1/trips/start \
  -H "X-API-Key: bkv_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_id": "vehicle_123",
    "driver_id": "driver_456",
    "metadata": {
      "purpose": "delivery",
      "route_name": "Route A"
    }
  }'

2. Active State

Once started, trips are in an active state and can:

Receive location updates via batch or single upload
Accumulate analytics and safety metrics
Generate real-time events and alerts
Be monitored through streaming connections

3. Trip Completion

Trips are completed by calling the stop trip endpoint:

curl -X POST https://api.bookovia.com/v1/trips/{trip_id}/stop \
  -H "X-API-Key: bkv_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "end_location": {
      "latitude": 40.7589,
      "longitude": -73.9851
    },
    "odometer_reading": 125678
  }'

Trip Data Model

Core Properties

{
  "trip_id": "trip_1234567890abcdef",
  "organization_id": "org_abcdef123456",
  "vehicle_id": "vehicle_123",
  "driver_id": "driver_456",
  "status": "active",
  "start_time": "2024-04-13T08:30:00Z",
  "end_time": null,
  "start_location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "New York, NY"
  },
  "end_location": null,
  "metadata": {
    "purpose": "delivery",
    "route_name": "Downtown Route",
    "customer_id": "cust_789",
    "priority": "high"
  }
}

Analytics Properties

{
  "analytics": {
    "distance_km": 45.7,
    "duration_minutes": 67,
    "max_speed_kmh": 85,
    "avg_speed_kmh": 42,
    "idle_time_minutes": 12,
    "fuel_consumed_liters": 4.2,
    "safety_score": 87,
    "eco_score": 92,
    "locations_count": 892,
    "events_count": 3
  }
}

Safety Metrics

{
  "safety_metrics": {
    "harsh_acceleration_count": 2,
    "harsh_braking_count": 1,
    "harsh_cornering_count": 0,
    "speeding_events": 1,
    "phone_usage_detected": false,
    "fatigue_indicators": 0,
    "crash_risk_score": "low"
  }
}

Trip States

State	Description	Allowed Actions
active	Trip is in progress	Upload locations, get real-time data, stop trip
completed	Trip has ended	View analytics, export data, generate reports
paused	Trip temporarily suspended	Resume trip, upload locations, stop trip
cancelled	Trip was cancelled	View partial data (read-only)

Working with Trips

Starting a Trip

When starting a trip, you can provide:

Required: vehicle_id - The vehicle identifier
Optional: driver_id - The driver identifier
Optional: metadata - Custom data for your application
Optional: start_location - Manual start location (auto-detected if not provided)

const trip = await client.trips.start({
  vehicleId: 'fleet_vehicle_42',
  driverId: 'emp_john_doe',
  metadata: {
    delivery_id: 'DEL_123456',
    customer_name: 'ABC Corp',
    expected_duration: 45,
    route_type: 'urban'
  },
  startLocation: {
    latitude: 40.7128,
    longitude: -74.0060
  }
});

Uploading Location Data

During an active trip, location data can be uploaded:

Single Location Upload

For real-time updates:

await client.locations.upload({
  tripId: 'trip_123',
  latitude: 40.7589,
  longitude: -73.9851,
  timestamp: new Date().toISOString(),
  speed: 35,
  heading: 180,
  accuracy: 5
});

Batch Location Upload

For efficiency with multiple points:

await client.locations.batchUpload({
  tripId: 'trip_123',
  locations: [
    {
      latitude: 40.7589,
      longitude: -73.9851,
      timestamp: '2024-04-13T08:30:00Z',
      speed: 35,
      heading: 180
    },
    {
      latitude: 40.7610,
      longitude: -73.9840,
      timestamp: '2024-04-13T08:30:30Z',
      speed: 42,
      heading: 175
    }
  ]
});

Retrieving Trip Data

Get Single Trip

const trip = await client.trips.get('trip_123');
console.log(trip.analytics.distance_km);

List Trips with Filters

const trips = await client.trips.list({
  vehicleId: 'vehicle_123',
  startDate: '2024-04-01',
  endDate: '2024-04-13',
  status: 'completed',
  limit: 50
});

Get Trip Summary

const summary = await client.trips.getSummary('trip_123');
console.log(summary.safety_score);

Trip Events

Trips automatically generate events based on driving behavior:

Event Types

Event Type	Description	Trigger Conditions
harsh_acceleration	Sudden acceleration	> 3.5 m/s² for 2+ seconds
harsh_braking	Sudden deceleration	> -4.0 m/s² for 1+ seconds
harsh_cornering	Sharp turns	Lateral G-force > 0.6g
speeding	Speed limit violation	> posted speed + threshold
idle_excessive	Unnecessary idling	Engine on, speed 0 for 5+ minutes
phone_usage	Phone usage while driving	Detected via accelerometer patterns

Event Data Structure

{
  "event_id": "evt_1234567890abcdef",
  "trip_id": "trip_1234567890abcdef", 
  "event_type": "harsh_braking",
  "severity": "medium",
  "timestamp": "2024-04-13T08:45:22Z",
  "location": {
    "latitude": 40.7589,
    "longitude": -73.9851
  },
  "details": {
    "deceleration": -4.2,
    "duration_seconds": 2.1,
    "speed_before": 55,
    "speed_after": 25
  }
}

Trip Analytics

Real-time Analytics

During active trips, analytics are computed in real-time:

// Get live trip statistics
const analytics = await client.trips.getAnalytics('trip_123');

console.log(`Distance: ${analytics.distance_km} km`);
console.log(`Duration: ${analytics.duration_minutes} minutes`);
console.log(`Safety Score: ${analytics.safety_score}/100`);

Post-trip Analysis

After completion, comprehensive analytics become available:

Route Optimization: Suggested route improvements
Fuel Efficiency: Consumption analysis and recommendations
Driver Coaching: Behavior insights and improvement suggestions
Predictive Maintenance: Vehicle health indicators

Use Cases

Fleet Management

// Monitor all active trips for a fleet
const activeTrips = await client.trips.list({
  status: 'active',
  organizationId: 'fleet_company_123'
});

// Check for trips with safety concerns
const riskyTrips = activeTrips.filter(trip => 
  trip.analytics.safety_score < 70
);

Delivery Optimization

// Track delivery performance
const deliveryTrip = await client.trips.start({
  vehicleId: 'delivery_van_05',
  driverId: 'driver_sarah',
  metadata: {
    delivery_window_start: '09:00',
    delivery_window_end: '11:00',
    packages_count: 12,
    priority: 'express'
  }
});

Insurance Telematics

// Generate insurance score based on driving behavior
const monthlyTrips = await client.trips.list({
  driverId: 'policy_holder_456',
  startDate: '2024-03-01',
  endDate: '2024-03-31'
});

const insuranceScore = monthlyTrips.reduce((acc, trip) => 
  acc + trip.analytics.safety_score, 0) / monthlyTrips.length;

Best Practices

Performance Optimization

Batch Location Uploads

Upload locations in batches of 10-100 points
Use compression for large batches
Implement retry logic with exponential backoff

Efficient Querying

Use date ranges to limit result sets
Implement pagination for large datasets
Cache frequently accessed trip data

Real-time Monitoring

Use WebSocket connections for live updates
Implement proper error handling for connection drops
Buffer data during connectivity issues

Data Quality

Location Accuracy

Filter out GPS points with low accuracy (> 50m)
Remove duplicate consecutive points
Validate coordinate ranges and impossible speeds

Trip Validation

Ensure trips have minimum duration (> 30 seconds)
Validate start/stop locations are reasonable
Check for data completeness before analysis

Troubleshooting

Common Issues

Trip Not Starting

Symptoms: Start trip API returns errorSolutions:

Verify vehicle_id exists and is active
Check for existing active trip on same vehicle
Ensure API key has trip:write permissions

Missing Location Data

Symptoms: Trip shows no or incomplete routeSolutions:

Verify location uploads are successful (check response codes)
Ensure timestamps are in correct format (ISO 8601)
Check for GPS accuracy issues

Inaccurate Analytics

Symptoms: Distance/duration calculations seem wrongSolutions:

Review location data quality (accuracy, gaps)
Check for GPS drift or tunnels
Verify timezone handling in timestamps

Next Steps

Location Data

Learn about GPS coordinates and location data management

Safety Analytics

Understand how safety scores and events are calculated

Start Trip API

Detailed API reference for starting trips

Real-time Streaming

Stream live trip data with WebSocket connections

Ready to start tracking trips? Check out our quickstart guide for a step-by-step tutorial.

Get Started

Core Concepts

Integration Guides

Trips

Trips

What is a Trip?

Trip Lifecycle

1. Trip Creation

2. Active State

3. Trip Completion

Trip Data Model

Core Properties

Analytics Properties

Safety Metrics

Trip States

Working with Trips

Starting a Trip

Uploading Location Data

Retrieving Trip Data

Trip Events

Event Types

Event Data Structure

Trip Analytics

Real-time Analytics

Post-trip Analysis

Use Cases

Fleet Management

Delivery Optimization

Insurance Telematics

Best Practices

Performance Optimization

Data Quality

Troubleshooting

Common Issues

Next Steps

Location Data

Safety Analytics

Start Trip API

Real-time Streaming

Get Started

Core Concepts

Integration Guides

Documentation Index

​Trips

​What is a Trip?

​Trip Lifecycle

​1. Trip Creation

​2. Active State

​3. Trip Completion

​Trip Data Model

​Core Properties

​Analytics Properties

​Safety Metrics

​Trip States

​Working with Trips

​Starting a Trip

​Uploading Location Data

​Retrieving Trip Data

​Trip Events

​Event Types

​Event Data Structure

​Trip Analytics

​Real-time Analytics

​Post-trip Analysis

​Use Cases

​Fleet Management

​Delivery Optimization

​Insurance Telematics

​Best Practices

​Performance Optimization

​Data Quality

​Troubleshooting

​Common Issues

​Next Steps

Location Data

Safety Analytics

Start Trip API

Real-time Streaming

Trips

What is a Trip?

Trip Lifecycle

1. Trip Creation

2. Active State

3. Trip Completion

Trip Data Model

Core Properties

Analytics Properties

Safety Metrics

Trip States

Working with Trips

Starting a Trip

Uploading Location Data

Retrieving Trip Data

Trip Events

Event Types

Event Data Structure

Trip Analytics

Real-time Analytics

Post-trip Analysis

Use Cases

Fleet Management

Delivery Optimization

Insurance Telematics

Best Practices

Performance Optimization

Data Quality

Troubleshooting

Common Issues

Next Steps