Skip to main content
GuidesAPI ReferenceExamples

Trips API

|

Record and analyze complete asset journeys with route tracking and stop management.

Overview​

Trips track complete journeys from start to end, recording the full route path, planned stops, and metadata. Trip summaries provide comprehensive analytics including distance, duration, and location count. A trip may represent a delivery, a pickup or something else.

Trip Object Fields​

FieldTypeDescription
idStringUnique identifier for the trip. Auto-generated UUID if not provided.
asset_idStringIdentifier of the asset performing the trip.
stateStringCurrent state of the trip: active (in progress) or ended (completed).
nameStringHuman-readable name for the trip.
descriptionStringDetailed description of the trip purpose.
meta_dataObjectCustom JSON metadata for flexible trip categorization (e.g., shift, route_type, priority).
attributesObjectCustom JSON attributes for additional trip information.
started_atIntegerUnix timestamp when the trip started.
ended_atIntegerUnix timestamp when the trip ended (null if active).
created_atIntegerUnix timestamp when the trip was created.
updated_atIntegerUnix timestamp when the trip was last updated.
stopsArrayOptional list of planned stops with geofence references and metadata.
routeArrayGPS trace points representing the journey path.
distance_mNumber(Ended trip summary only) Total distance traveled in meters.
duration_sInteger(Ended trip summary only) Total trip duration in seconds.
location_countInteger(Ended trip summary only) Number of GPS trace points recorded.

Start Trip​

Initiate a new trip for an asset.

  • Endpoint: POST /start_trip

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_trip_id": "delivery_trip_001",
  "p_asset_id": "vehicle_101",
  "p_name": "Downtown Delivery Route",
  "p_description": "Morning delivery run covering downtown area",
  "p_meta_data": {
    "shift": "morning",
    "route_type": "delivery",
    "priority": "high"
  },
  "p_attributes": {
    "driver_name": "John Smith",
    "estimated_duration_minutes": 120,
    "package_count": 15
  },
  "p_stops": [
    {
      "name": "Main Warehouse",
      "meta_data": {
        "stop_type": "pickup"
      },
      "geofence_id": "warehouse_safety_perimeter"
    },
    {
      "name": "Downtown Office Building A",
      "meta_data": {
        "stop_type": "delivery",
        "packages": 5
      },
      "geofence_id": "downtown_delivery_zone"
    }
  ]
}

Parameters:

  • p_trip_id (optional) - Custom identifier (UUID auto-generated if not provided)

  • p_asset_id - Asset performing the trip

  • p_name - Trip name/title

  • p_description - Detailed description

  • p_meta_data (optional) - Custom JSON metadata

  • p_attributes (optional) - Custom JSON attributes

  • p_stops (optional) - Array of planned stops with geofence references

  • Response Body: (code 200 OK)

{
    "trip_id": "delivery_trip_001",
    "error": ""
}

Get Trip Information​

Retrieve complete trip details including route data.

  • Endpoint: GET /get_trip_by_id

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_trip_id": "delivery_trip_001"
}
  • Response Body: (code 200 OK)
{
    "status": "Ok",
    "data": {
        "trip": {
            "id": "delivery_trip_001",
            "asset_id": "vehicle_101",
            "state": "active",
            "name": "Downtown Delivery Route",
            "description": "Morning delivery run covering downtown area",
            "meta_data": {
                "shift": "morning",
                "priority": "high",
                "route_type": "delivery"
            },
            "attributes": {
                "driver_name": "John Smith",
                "package_count": 15,
                "start_location": "Main Warehouse",
                "estimated_duration_minutes": 120
            },
            "started_at": 1767863673,
            "ended_at": null,
            "created_at": 1767863673,
            "updated_at": 1767863673,
            "stops": [
                {
                    "name": "Main Warehouse",
                    "meta_data": {
                        "stop_type": "pickup",
                        "entry_point": "loading_dock_3",
                        "arrival_time": "08:00"
                    },
                    "geofence_id": "warehouse_safety_perimeter"
                },
                {
                    "name": "Downtown Office Building A",
                    "meta_data": {
                        "packages": 5,
                        "stop_type": "delivery",
                        "entry_point": "main_entrance"
                    },
                    "geofence_id": "downtown_delivery_zone"
                },
                {
                    "name": "Downtown Office Building B",
                    "meta_data": {
                        "packages": 10,
                        "stop_type": "delivery",
                        "entry_point": "side_entrance"
                    },
                    "geofence_id": "downtown_delivery_zone"
                }
            ],
            "route": [
                {
                    "accuracy": 0.5,
                    "altitude": null,
                    "bearing": 45,
                    "location": {
                        "lat": 45.6485790625,
                        "lon": 25.6140759375
                    },
                    "meta_data": null,
                    "speed": 18,
                    "timestamp": 1767864327
                },
                {
                    "accuracy": 0.5,
                    "altitude": null,
                    "bearing": 50,
                    "location": {
                        "lat": 45.649011875,
                        "lon": 25.614433125
                    },
                    "meta_data": null,
                    "speed": 20,
                    "timestamp": 1767864810
                },
               ...
            ]
        }
    }
}

Response Fields:

  • id - Trip identifier
  • asset_id - Asset performing the trip
  • status - active or ended
  • started_at - Unix timestamp when trip started
  • ended_at - Unix timestamp when trip ended (null if active)
  • meta_data - Custom trip metadata
  • attributes - Custom trip attributes
  • stops - Array of planned stops
  • route - GPS trace of the journey (ongoing or complete if ended)

Use Cases:

  • Real-time trip progress monitoring
  • Route replay and visualization
  • Driver performance analysis

Update Trip​

Modify active trip information.

  • Endpoint: POST /update_trip

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_trip_id": "delivery_trip_001",
  "p_asset_id": "vehicle_101",
  "p_meta_data": {
    "status": "delayed",
    "delay_reason": "traffic_accident",
    "estimated_delay_minutes": 30
  }
}

Important: Only active trips can be updated. Once ended, trips become read-only.

  • Response Body: (code 200 OK)
{
    "id": "delivery_trip_001",
    "error": ""
}

End Trip​

Mark a trip as completed.

  • Endpoint: GET /end_trip_by_id

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_trip_id": "delivery_trip_001"
}
  • Response Body: (code 200 OK)
{
    "status": "Ok"
}

Get Trip Summary​

Retrieve analytics for completed trips.

  • Endpoint: GET /get_trip_summary

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_trip_id": "delivery_trip_001"
}

Summary includes:

  • distance_m - Total distance traveled in meters
  • duration_s - Total trip duration in seconds
  • location_count - Number of GPS trace points
  • Complete route data
  • Asset information
  • Start/end timestamps

Note: Trip summaries are only available for ended trips.

  • Response Body: (code 200 OK)
{
    "status": "Ok",
    "data": {
        "trip": {
            "id": "delivery_trip_001",
            "asset_id": "vehicle_101",
            "state": "ended",
            "name": "Downtown Delivery Route",
            "description": "Morning delivery run covering downtown area",
            "meta_data": {
                "shift": "morning",
                "status": "delayed",
                "priority": "high",
                "route_type": "delivery",
                "delay_reason": "traffic_accident",
                "estimated_delay_minutes": 30
            },
            "attributes": {
                "driver_name": "John Smith",
                "package_count": 15,
                "current_location": "Highway Exit 42",
                "estimated_duration_minutes": 150
            },
            "started_at": 1767863673,
            "ended_at": 1767866711,
            "created_at": 1767863673,
            "updated_at": 1767866711,
            "stops": [],
            "route": [
                {
                    "accuracy": 0.5,
                    "altitude": null,
                    "bearing": 45,
                    "location": {
                        "lat": 45.6485790625,
                        "lon": 25.6140759375
                    },
                    "meta_data": null,
                    "speed": 18,
                    "timestamp": 1767864327
                },
                ...
            ],
            "distance_m": 614.12314995,
            "duration_s": 711,
            "location_count": 11,
            "asset": {
                "id": "vehicle_101",
                "state": "active",
                "name": "Delivery Van 101 - Updated",
                "description": "Primary delivery vehicle for downtown and suburban routes",
                "created_at": 1766480112,
                "updated_at": 1766487603,
                "properties": {
                    "zone": "downtown",
                    "department": "logistics",
                    "capacity_kg": 1000,
                    "vehicle_type": "van",
                    "license_plate": "ABC-123"
                },
                "latest_location": {
                    "location": {
                        "lat": 45.6532890625,
                        "lon": 25.6182009375
                    },
                    "timestamp": 1767865038,
                    "accuracy": 0.5,
                    "speed": 8,
                    "bearing": 78,
                    "altitude": null
                }
            }
        }
    }
}

Delete Trips​

Remove trip records from the system.

  • Endpoint: DELETE /delete_trips

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_ids": ["old_trip_1", "test_trip"]
}
  • Response Body: (code 200 OK)
{
    "deleted_ids": [
        "old_trip_1", 
        "test_trip"
    ]
}

Trip Workflow Example​

// 1. Start trip
POST /start_trip
{
  "p_asset_id": "vehicle_101",
  "p_name": "Morning Route",
  "p_stops": [...]
}

// 2. Update during trip (optional)
POST /update_trip
{
  "p_trip_id": "...",
  "p_meta_data": { "current_stop": 2 }
}

// 3. End trip
GET /end_trip_by_id
{
  "p_trip_id": "..."
}

// 4. Get analytics
GET /get_trip_summary
{
  "p_trip_id": "..."
}

Notes​

  • Define stops with geofence IDs for automatic visit detection
  • Use meta_data for flexible trip categorization
  • Retrieve summaries after completion for reporting
  • Store trip IDs for historical reference

API Limits​

  • For requests that support pagination, entries per page can be set to maximum 1000
Last updated on