Skip to main content
GET
/
v1
/
trips
/
{trip_id}
Get Trip
curl --request GET \
  --url https://api.bookovia.com/v1/trips/{trip_id} \
  --header 'X-API-Key: <api-key>'
{
  "error": {
    "code": "trip_not_found",
    "message": "The specified trip_id was not found",
    "details": "Trip 'trip_1234567890abcdef' does not exist or is not associated with your organization"
  },
  "request_id": "req_1234567890abcdef"
}

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 endpoint returns comprehensive information about a specific trip, including current status, analytics, location history, and real-time metrics for active trips.
This endpoint provides real-time data for active trips and final analytics for completed trips.

​
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 retrieve
​
include_locations
boolean
default:"false"
Whether to include the full location history in the response. Use with caution for trips with many location points.
​
include_events
boolean
default:"true"
Whether to include driving events (harsh braking, acceleration, etc.) in the response
​
analytics_level
string
default:"standard"
Level of analytics detail to include. Options: “basic”, “standard”, “detailed”

​
Request Example

curl -X GET "https://api.bookovia.com/v1/trips/trip_1234567890abcdef?include_events=true&analytics_level=detailed" \
  -H "X-API-Key: bkv_test_your_api_key_here"

​
Response

​
trip_id
string
Unique identifier for the trip
​
organization_id
string
Organization that owns this trip
​
vehicle_id
string
Vehicle associated with the trip
​
driver_id
string
Driver associated with the trip (if assigned)
​
status
string
Current trip status: “active”, “completed”, “cancelled”, “interrupted”
​
start_time
string
ISO 8601 timestamp when the trip started
​
end_time
string
ISO 8601 timestamp when the trip ended (null for active trips)
​
locations
array
Array of location points (only included if include_locations=true)
​
analytics
object
Trip analytics and performance metrics

​
Success Response

{
  "trip_id": "trip_1234567890abcdef",
  "organization_id": "org_abcdef123456",
  "vehicle_id": "vehicle_123",
  "driver_id": "driver_456",
  "status": "active",
  "start_time": "2024-04-13T10:30:00Z",
  "end_time": null,
  "start_location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "New York, NY, USA"
  },
  "end_location": null,
  "current_location": {
    "latitude": 40.7359,
    "longitude": -73.9911,
    "timestamp": "2024-04-13T11:45:00Z",
    "speed_kmh": 45.2,
    "heading": 87
  },
  "metadata": {
    "purpose": "delivery",
    "route_name": "Downtown Route A",
    "customer_id": "cust_789",
    "priority": "high"
  },
  "analytics": {
    "distance_km": 15.7,
    "duration_minutes": 75,
    "avg_speed_kmh": 32.1,
    "max_speed_kmh": 78,
    "idle_time_minutes": 3.2,
    "locations_count": 187,
    "safety_score": 89,
    "eco_score": 85,
    "events_summary": {
      "total_events": 1,
      "harsh_acceleration": 0,
      "harsh_braking": 1,
      "harsh_cornering": 0,
      "speeding_incidents": 0
    },
    "route_efficiency": {
      "planned_distance_km": 16.2,
      "actual_distance_km": 15.7,
      "efficiency_percentage": 96.9
    }
  },
  "events": [
    {
      "event_id": "evt_harsh_brake_001",
      "type": "harsh_braking",
      "severity": "moderate",
      "timestamp": "2024-04-13T11:22:15Z",
      "location": {
        "latitude": 40.7298,
        "longitude": -73.9973
      },
      "metrics": {
        "deceleration_g": -0.42,
        "speed_before_kmh": 55,
        "speed_after_kmh": 15
      }
    }
  ],
  "created_at": "2024-04-13T10:30:00Z",
  "updated_at": "2024-04-13T11:45:00Z"
}

​
Error Responses

{
  "error": {
    "code": "trip_not_found",
    "message": "The specified trip_id was not found",
    "details": "Trip 'trip_1234567890abcdef' does not exist or is not associated with your organization"
  },
  "request_id": "req_1234567890abcdef"
}

​
SDK Examples

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

const client = new Bookovia('bkv_test_your_api_key');

// Get basic trip information
const trip = await client.trips.get('trip_1234567890abcdef');

// Get detailed trip information with events
const detailedTrip = await client.trips.get('trip_1234567890abcdef', {
  includeEvents: true,
  analyticsLevel: 'detailed'
});

console.log(`Trip status: ${trip.status}`);
console.log(`Safety score: ${trip.analytics.safetyScore}`);

​
Use Cases

​
Real-time Trip Monitoring

// Monitor active trip in real-time
const monitorTrip = async (tripId) => {
  const trip = await client.trips.get(tripId, { analyticsLevel: 'detailed' });
  
  if (trip.status === 'active') {
    console.log(`Current location: ${trip.currentLocation.latitude}, ${trip.currentLocation.longitude}`);
    console.log(`Distance traveled: ${trip.analytics.distanceKm} km`);
    console.log(`Current safety score: ${trip.analytics.safetyScore}`);
  }
};

// Poll every 30 seconds
setInterval(() => monitorTrip('trip_123'), 30000);

​
Fleet Dashboard

# Get trip data for fleet dashboard
async def get_fleet_trip_data(trip_ids):
    trips = []
    for trip_id in trip_ids:
        trip = await client.trips.get(trip_id, analytics_level='standard')
        trips.append({
            'trip_id': trip.trip_id,
            'vehicle_id': trip.vehicle_id,
            'status': trip.status,
            'safety_score': trip.analytics.safety_score,
            'distance_km': trip.analytics.distance_km
        })
    return trips

​
Next Steps

Get Trip Summary

Get detailed analytics and performance summary

List Trips

Browse all trips for a vehicle or organization

Update Trip Metadata

Modify trip metadata and custom fields

Stop Trip

End an active trip and finalize analytics