Bookovia Telematics API Documentation

Overview

The Start Trip endpoint creates a new trip for a vehicle and optionally a driver. Once started, the trip enters an active state and can receive location data through the location upload endpoints.

Each vehicle can only have one active trip at a time. Starting a new trip while another is active will return an error.

Authentication

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

Request

vehicle_id

string

required

Unique identifier for the vehicle. Must be a valid vehicle ID associated with your organization.

driver_id

string

Unique identifier for the driver. If not provided, the trip will be created without a driver association.

start_location

object

Manual start location for the trip. If not provided, the location will be automatically detected from the first GPS point uploaded.

Show start_location properties

latitude

number

required

Latitude coordinate in decimal degrees (-90 to 90)

longitude

number

required

Longitude coordinate in decimal degrees (-180 to 180)

address

string

Human-readable address for the location. If not provided, the address will be automatically geocoded from the coordinates using Mapbox Geocoding API.

Automatic Reverse Geocoding: When start_location is provided without an address, the API automatically geocodes the coordinates to a human-readable address (e.g., “129 Macdougal Street, New York, New York 10012, United States”). This address is stored in telematics_trip_events.address for the start event.

metadata

object

Custom metadata for the trip. Can include any JSON-serializable data relevant to your application.

Show Common metadata fields

purpose

string

Purpose of the trip (e.g., “delivery”, “service”, “personal”)

route_name

string

Name or identifier for the planned route

customer_id

string

Customer identifier for delivery or service trips

priority

string

Trip priority level (e.g., “low”, “normal”, “high”, “urgent”)

expected_duration_minutes

integer

Expected trip duration in minutes

planned_distance_km

number

Planned trip distance in kilometers

odometer_reading

integer

Vehicle odometer reading at trip start (in kilometers or miles based on your organization settings)

fuel_level_percent

number

Fuel level percentage at trip start (0-100)

Request Example

curl -X POST https://api.bookovia.com/v1/trips/start \
  -H "X-API-Key: bkv_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_id": "vehicle_123",
    "driver_id": "driver_456",
    "start_location": {
      "latitude": 40.7128,
      "longitude": -74.0060,
      "address": "New York, NY"
    },
    "metadata": {
      "purpose": "delivery",
      "route_name": "Downtown Route A",
      "customer_id": "cust_789",
      "priority": "high",
      "expected_duration_minutes": 45
    },
    "odometer_reading": 125430,
    "fuel_level_percent": 85
  }'

Response

trip_id

string

Unique identifier for the created trip. Use this ID for all subsequent trip operations.

organization_id

string

Organization identifier that owns this trip

vehicle_id

string

Vehicle identifier associated with the trip

driver_id

string

Driver identifier associated with the trip (if provided)

status

string

Current trip status. Will be “active” for newly created trips.

start_time

string

ISO 8601 timestamp when the trip was started

start_location

object

Starting location information

Show start_location properties

latitude

number

Starting latitude coordinate

longitude

number

Starting longitude coordinate

address

string

Resolved address for the starting location

metadata

object

Custom metadata provided during trip creation

analytics

object

Initial analytics object (mostly null/zero values for new trips)

Show analytics properties

distance_km

number

Total distance traveled (0 for new trips)

duration_minutes

number

Trip duration in minutes (0 for new trips)

max_speed_kmh

number

Maximum speed reached (null for new trips)

avg_speed_kmh

number

Average speed (null for new trips)

safety_score

integer

Safety score from 0-100 (null until location data is available)

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,
  "metadata": {
    "purpose": "delivery",
    "route_name": "Downtown Route A",
    "customer_id": "cust_789", 
    "priority": "high",
    "expected_duration_minutes": 45
  },
  "analytics": {
    "distance_km": 0,
    "duration_minutes": 0,
    "max_speed_kmh": null,
    "avg_speed_kmh": null,
    "idle_time_minutes": 0,
    "locations_count": 0,
    "events_count": 0,
    "safety_score": null,
    "eco_score": null
  },
  "created_at": "2024-04-13T10:30:00Z",
  "updated_at": "2024-04-13T10:30:00Z"
}

Error Responses

{
  "error": {
    "code": "invalid_vehicle_id",
    "message": "The specified vehicle_id is invalid or not found",
    "details": "Vehicle 'vehicle_123' 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');

const trip = await client.trips.start({
  vehicleId: 'vehicle_123',
  driverId: 'driver_456',
  startLocation: {
    latitude: 40.7128,
    longitude: -74.0060
  },
  metadata: {
    purpose: 'delivery',
    routeName: 'Downtown Route A'
  }
});

console.log(`Trip started: ${trip.tripId}`);

Use Cases

Fleet Delivery Management

// Start delivery trip with comprehensive tracking
const deliveryTrip = await client.trips.start({
  vehicleId: 'delivery_van_05',
  driverId: 'emp_sarah_johnson',
  metadata: {
    purpose: 'delivery',
    delivery_batch_id: 'BATCH_2024_0413_001',
    packages_count: 12,
    estimated_stops: 8,
    priority: 'express',
    customer_service_level: 'premium'
  }
});

Service Call Tracking

# Track service technician trip
service_trip = await client.trips.start(
    vehicle_id='service_truck_12',
    driver_id='tech_mike_wilson', 
    metadata={
        'purpose': 'service_call',
        'work_order_id': 'WO_789456',
        'customer_id': 'CUST_ABC123',
        'service_type': 'maintenance',
        'priority': 'urgent',
        'estimated_duration': 120
    }
)

Personal Vehicle Tracking

// Start personal trip tracking
trip, err := client.Trips.Start(ctx, &bookovia.StartTripRequest{
    VehicleID: "personal_car_001",
    DriverID:  "family_member_dad",
    Metadata: map[string]interface{}{
        "purpose": "commute",
        "route_type": "home_to_work",
        "passengers": 1,
    },
})

Best Practices

Data Validation

Vehicle ID Validation

Ensure vehicle_id exists in your system before starting trip
Check that vehicle is not already on an active trip
Verify vehicle is in operational status

Location Data Quality

Validate latitude/longitude ranges before sending
Provide address when available for better reporting
Consider accuracy requirements for your use case

Metadata Structure

Use consistent metadata schemas across your application
Keep metadata reasonably sized (< 10KB)
Use typed fields where possible for better analytics

Error Handling

Active Trip Conflicts

try {
  const trip = await client.trips.start({vehicleId: 'vehicle_123'});
} catch (error) {
  if (error.code === 'active_trip_exists') {
    // Handle existing active trip
    const activeTrip = error.activeTripId;
    // Option 1: Stop existing trip first
    // Option 2: Show error to user
    // Option 3: Resume existing trip
  }
}

Vehicle Validation

try:
    trip = await client.trips.start(vehicle_id='vehicle_123')
except bookovia.InvalidVehicleError as e:
    # Handle invalid vehicle ID
    logger.error(f"Invalid vehicle: {e.vehicle_id}")
    # Fetch valid vehicle list or prompt user

Performance Optimization

Batch Operations: If starting multiple trips, consider using bulk endpoints (enterprise feature)
Caching: Cache vehicle and driver information to avoid repeated validation
Async Processing: Use async/await patterns to avoid blocking UI

Rate Limits

This endpoint is subject to the following rate limits:

Standard: 100 requests per minute
Professional: 500 requests per minute
Enterprise: 2,000 requests per minute

Next Steps

After starting a trip, you’ll typically want to:

Upload Location Data

Start uploading GPS coordinates to track the vehicle’s journey

Monitor Trip Progress

Check trip status and real-time analytics

Set Up Real-time Streaming

Stream live location data and events

Stop Trip

Learn how to properly end the trip when completed

Need help? Contact our support team at support@bookovia.com or check our troubleshooting guide.

Trip Management

Routing & Navigation

Maps & Vector Tiles

Geocoding & Places

Location Data

Safety Analytics

Fleet Management

Real-time Streaming

Device Management

Emergency & Alerts

Start Trip

Overview

Authentication

Request

Request Example

Response

Success Response

Error Responses

SDK Examples

Use Cases

Fleet Delivery Management

Service Call Tracking

Personal Vehicle Tracking

Best Practices

Data Validation

Error Handling

Performance Optimization

Rate Limits

Next Steps

Upload Location Data

Monitor Trip Progress

Set Up Real-time Streaming

Stop Trip

Trip Management

Routing & Navigation

Maps & Vector Tiles

Geocoding & Places

Location Data

Safety Analytics

Fleet Management

Real-time Streaming

Device Management

Emergency & Alerts

Documentation Index

​Overview

​Authentication

​Request

​Request Example

​Response

​Success Response

​Error Responses

​SDK Examples

​Use Cases

​Fleet Delivery Management

​Service Call Tracking

​Personal Vehicle Tracking

​Best Practices

​Data Validation

​Error Handling

​Performance Optimization

​Rate Limits

​Next Steps

Upload Location Data

Monitor Trip Progress

Set Up Real-time Streaming

Stop Trip

Overview

Authentication

Request

Request Example

Response

Success Response

Error Responses

SDK Examples

Use Cases

Fleet Delivery Management

Service Call Tracking

Personal Vehicle Tracking

Best Practices

Data Validation

Error Handling

Performance Optimization

Rate Limits

Next Steps