Skip to main content
POST
/
v1
/
trips
/
{trip_id}
/
stop
Stop Trip
curl --request POST \
  --url https://api.bookovia.com/v1/trips/{trip_id}/stop \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "end_location": {
    "latitude": 123,
    "longitude": 123,
    "address": "<string>"
  },
  "odometer_reading": 123,
  "fuel_level_percent": 123,
  "completion_status": "<string>"
}
'
{
  "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 Stop Trip endpoint finalizes an active trip, processes all collected location data, and generates comprehensive analytics including safety scores, route analysis, and performance metrics.
Stopping a trip is irreversible. Ensure all location data has been uploaded before stopping the trip.

Authentication

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

Request

trip_id
string
required
Unique identifier for the trip to stop. Must be an active trip associated with your organization.
end_location
object
Manual end location for the trip. If not provided, the location will be automatically detected from the last GPS point uploaded.
odometer_reading
integer
Vehicle odometer reading at trip end (in kilometers or miles based on your organization settings)
fuel_level_percent
number
Fuel level percentage at trip end (0-100)
completion_status
string
Status indicating how the trip was completed. Options: “completed”, “cancelled”, “interrupted”

Request Example

curl -X POST https://api.bookovia.com/v1/trips/trip_1234567890abcdef/stop \
  -H "X-API-Key: bkv_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "end_location": {
      "latitude": 40.7589,
      "longitude": -73.9851,
      "address": "Central Park, New York, NY"
    },
    "odometer_reading": 125475,
    "fuel_level_percent": 68,
    "completion_status": "completed"
  }'

Response

trip_id
string
Unique identifier for the stopped trip
status
string
Trip status, will be “completed”, “cancelled”, or “interrupted”
end_time
string
ISO 8601 timestamp when the trip was stopped
end_location
object
Final location information
analytics
object
Comprehensive trip analytics and performance metrics

Success Response

{
  "trip_id": "trip_1234567890abcdef",
  "organization_id": "org_abcdef123456",
  "vehicle_id": "vehicle_123",
  "driver_id": "driver_456",
  "status": "completed",
  "start_time": "2024-04-13T10:30:00Z",
  "end_time": "2024-04-13T12:15:00Z",
  "start_location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "New York, NY, USA"
  },
  "end_location": {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "address": "Central Park, New York, NY, USA"
  },
  "analytics": {
    "distance_km": 45.2,
    "duration_minutes": 105,
    "max_speed_kmh": 85,
    "avg_speed_kmh": 32.4,
    "idle_time_minutes": 8.5,
    "locations_count": 426,
    "events_count": 3,
    "safety_score": 87,
    "eco_score": 82,
    "harsh_events": {
      "harsh_acceleration": 1,
      "harsh_braking": 2,
      "harsh_cornering": 0,
      "speeding": 0
    },
    "fuel_efficiency": {
      "fuel_consumed_liters": 4.2,
      "fuel_efficiency_kmpl": 10.8
    }
  },
  "updated_at": "2024-04-13T12:15: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');

const completedTrip = await client.trips.stop('trip_1234567890abcdef', {
  endLocation: {
    latitude: 40.7589,
    longitude: -73.9851
  },
  completionStatus: 'completed'
});

console.log(`Trip completed with safety score: ${completedTrip.analytics.safetyScore}`);

Next Steps

After stopping a trip, you can:

Get Trip Summary

Retrieve detailed analytics and performance metrics

Generate Reports

Create comprehensive driving behavior reports