Skip to content
/
Planning a Multi-Stop Tri...
Last updated

Planning a Multi-Stop Trip

Objective

Plan a trip with multiple pickup and delivery stops, assign a vehicle and chauffeur, and calculate the optimal route.

Scenario

You need to deliver goods from a warehouse in Rotterdam to two customers in Amsterdam and Utrecht, with a return to the depot.

Step 1: Create the Transport Order

curl -X POST https://api.otms.transportial.com/api/transportOrder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Multi-drop RTD → AMS + UTR",
    "status": "requested",
    "consignments": [
      {
        "name": "Amsterdam delivery",
        "status": "requested",
        "goods": [
          {
            "type": "items",
            "description": "Consumer electronics",
            "quantity": 30,
            "weight": { "value": 600, "unit": "kg" }
          }
        ]
      },
      {
        "name": "Utrecht delivery",
        "status": "requested",
        "goods": [
          {
            "type": "items",
            "description": "Office supplies",
            "quantity": 15,
            "weight": { "value": 200, "unit": "kg" }
          }
        ]
      }
    ]
  }'

Step 2: Create the Trip with Route Calculation

Use the :route endpoint to create the trip with automatic route calculation. Define the actions in order:

curl -X POST https://api.otms.transportial.com/api/trip:route \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Multi-drop trip RTD-AMS-UTR",
    "type": "road",
    "vehicle": { "id": "truck-uuid" },
    "chauffeurs": [{ "id": "chauffeur-uuid" }],
    "actions": [
      {
        "type": "load",
        "location": { "id": "rotterdam-warehouse-uuid" },
        "startTime": "2026-03-23T07:00:00Z",
        "endTime": "2026-03-23T07:45:00Z"
      },
      {
        "type": "move"
      },
      {
        "type": "unload",
        "location": { "id": "amsterdam-customer-uuid" },
        "startTime": "2026-03-23T08:30:00Z",
        "endTime": "2026-03-23T09:00:00Z"
      },
      {
        "type": "move"
      },
      {
        "type": "unload",
        "location": { "id": "utrecht-customer-uuid" },
        "startTime": "2026-03-23T10:00:00Z",
        "endTime": "2026-03-23T10:30:00Z"
      },
      {
        "type": "move"
      },
      {
        "type": "stop",
        "location": { "id": "rotterdam-warehouse-uuid" },
        "startTime": "2026-03-23T11:30:00Z"
      }
    ]
  }'

Response:

{
  "success": true,
  "message": "OK",
  "trip": {
    "id": "trip-uuid",
    "name": "Multi-drop trip RTD-AMS-UTR",
    "status": "planned",
    "routeStatus": "calculated",
    "estimatedDuration": 16200,
    "route": {
      "distance": 142.5,
      "geometry": "..."
    },
    "actions": [
      { "id": "action-1", "type": "load", "status": "planned" },
      { "id": "action-2", "type": "move", "status": "planned" },
      { "id": "action-3", "type": "unload", "status": "planned" },
      { "id": "action-4", "type": "move", "status": "planned" },
      { "id": "action-5", "type": "unload", "status": "planned" },
      { "id": "action-6", "type": "move", "status": "planned" },
      { "id": "action-7", "type": "stop", "status": "planned" }
    ]
  }
}

Step 3: Confirm the Trip

curl -X GET "https://api.otms.transportial.com/api/trip/{trip-uuid}/confirm" \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 4: Start the Trip

When the driver begins:

curl -X GET "https://api.otms.transportial.com/api/trip/{trip-uuid}/start" \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 5: Update Action Times as Execution Happens

As the driver completes each action, update the actual times:

# Mark loading complete
curl -X PUT "https://api.otms.transportial.com/api/trip/{trip-uuid}/action/{action-1}/times" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "startTime": "2026-03-23T07:05:00Z",
    "endTime": "2026-03-23T07:50:00Z"
  }'

# Mark Amsterdam unload complete
curl -X PUT "https://api.otms.transportial.com/api/trip/{trip-uuid}/action/{action-3}/times" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "startTime": "2026-03-23T08:40:00Z",
    "endTime": "2026-03-23T09:10:00Z"
  }'

Step 6: Finish the Trip

curl -X GET "https://api.otms.transportial.com/api/trip/{trip-uuid}/finish" \
  -H "Authorization: Bearer YOUR_TOKEN"

Key Takeaways

  • Use trip:route to create trips with automatic route calculation
  • Actions are executed in order — load → move → unload → move → unload → move → stop
  • Update action times with actual timestamps as the driver progresses
  • The route response includes distance and geometry for map visualization
Previous page
Next page